API References

kubernetes_lite

Kubernetes_lite is a lightweight wrapper around the dynamic client from k8s.io/client-go/dynamic, the 'mock' kubernetes server from sigs.k8s.io/controller-runtime/pkg/envtest, and its helper tool setup-envtest https://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest

kubernetes_lite.client

This module contains a simple pythonic wrapper around the k8s.io/client-go/dynamic DynamicClient.

DynamicClient

DynamicClient is the top level client and generic controls settings like authentication, rate limiting, and timeouts. Use the .resource method to create a DynamicResource which can be used to interact with the cluster.

resources cached property

Return the client's Discover object. It's preferred to use the resource() function instead of accessing this directly

Returns:

Name	Type	Description
Discoverer	Discoverer	The discover used in created DynamicResources

__init__(config=None, qps=-1, burst=100, timeout='', **kwargs)

Initialize the dynamic client with optional overrides

Parameters:

Name	Type	Description	Default
config	bytes | BytesIO | None	The raw kube_config data to initialize the client with. Defaults to controller-runtime's GetConfig. See https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/client/config#GetConfig for more information.	None
qps	float	QPS to set for the client. See https://pkg.go.dev/k8s.io/client-go/rest#Config for more information. Defaults to -1 which means rate-limiting is disabled.	-1
burst	int	How many requests can the client burst to. See https://pkg.go.dev/k8s.io/client-go/rest#Config for more information. Defaults to 100.	100
timeout	timedelta | str	Timeout value for the client. If a string is provided check https://pkg.go.dev/time#ParseDuration for parsing information. Defaults to "" or no timeout.	''
**kwargs		Unused kwargs for backwards compatibility with kubernetes library	{}

resource(api_version, kind)

Return a DynamicResource for the given api_version and kind. This DynamicResource can then be used to interact with the cluster.

Parameters:

Name	Type	Description	Default
api_version	str	The api_version for the resource handle	required
kind	str	The kind for the resource handle	required

Returns:

Name	Type	Description
DynamicResource	DynamicResource	The DynamicResource handle for the requested type

DynamicResource

DynamicResource is the primary client for interacting with resources on the cluster. It's functions mirror the ResourceInterface provided by https://pkg.go.dev/k8s.io/client-go/dynamic#ResourceInterface. The parameters to the various functions map to the json names of the Options objects in https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1. For example list() parameter's map to ListOptions

__init__(resource)

Create a DynamicResource which points to a WrappedNamespaceableResourceInterface from go. This class should not be initialized directly and should instead be created by the client/discoverer

Parameters:

Name	Type	Description	Default
resource	WrappedNamespaceableResourceInterface	The WrappedNamespaceableResourceInterface to wrap	required

apply(resource, name=None, namespace=None, dry_run=None, field_manager=None, force=None, extra_options_kwargs=None, subresources=None, **kwargs)

Apply an object in the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ApplyOptions. See https://kubernetes.io/docs/reference/using-api/server-side-apply/ for more information

Parameters:

Name	Type	Description	Default
resource	SourceObjectType	The resource to deploy	required
name	str | None	Optional name for the resource. Defaults to None or name in the provided resources.	None
namespace	str | None	Optional namespace for the resource. Defaults to None or namespace in the provided resources.	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
field_manager	str | None	Optional field manager string to use to manage resource fields. Defaults to None.	None
force	bool | None	If the patch should be forced ignoring field_manager. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more ApplyOptions parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The applied object from the cluster in a dictionary

apply_status(resource, name=None, namespace=None, dry_run=None, field_manager=None, force=None, extra_options_kwargs=None, subresources=None, **kwargs)

Apply a status object in the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ApplyOptions. See https://kubernetes.io/docs/reference/using-api/server-side-apply/ for more information

Parameters:

Name	Type	Description	Default
resource	SourceObjectType	The resource to deploy	required
name	str | None	Optional name for the resource. Defaults to None or name in the provided resources.	None
namespace	str | None	Optional namespace for the resource. Defaults to None or namespace in the provided resources.	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
field_manager	str | None	Optional field manager string to use to manage resource fields. Defaults to None.	None
force	bool | None	If the patch should be forced ignoring field_manager. Defaults to None.	None
field_validation	str | None	Optional fieldValidation instructs the server on how to handle objects in the request containing unknown or duplicate fields. Defaults to None.	required
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more ApplyOptions parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The applied object from the cluster in a dictionary

create(resource, namespace=None, dry_run=None, field_manager=None, field_validation=None, extra_options_kwargs=None, subresources=None, **kwargs)

Create an object in the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#CreateOptions

Parameters:

Name	Type	Description	Default
resource	SourceObjectType	The resource to deploy	required
namespace	str | None	Optional namespace for the resource. Defaults to None or namespace in the provided resources.	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
field_manager	str | None	Optional field manager string to use to manage resource fields. Defaults to None.	None
field_validation	str | None	Optional fieldValidation instructs the server on how to handle objects in the request containing unknown or duplicate fields. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more CreateOption parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The created object from the cluster in a dictionary

delete(name, namespace=None, grace_period_seconds=None, propagation_policy=None, dry_run=None, ignore_store_read_error=None, extra_options_kwargs=None, **kwargs)

Delete an object from the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#DeleteOptions.

Parameters:

Name	Type	Description	Default
name	str	Name for the resource to delete.	required
namespace	str | None	Optional namespace for the resource. Defaults to None	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
grace_period_seconds	int | None	Optional time to wait for graceful termination before deleting the resource. Defaults to None.	None
propagation_policy	str | None	Optional DeletionPropagation decides how a deletion propagates to dependents of the object. See https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#DeletionPropagation for more information. Defaults to None.	None
ignore_store_read_error	bool | None	Optional override to force successful deletion even if there is an etcd store error. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more DeleteOptions parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	required
**kwargs		Unused kwargs for compatibility	{}

delete_collection(namespace=None, grace_period_seconds=None, propagation_policy=None, dry_run=None, limit=None, resource_version=None, resource_version_match=None, label_selector=None, field_selector=None, timeout=None, ignore_store_read_error=None, extra_delete_options_kwargs=None, extra_list_options_kwargs=None, **kwargs)

Delete a collection of objects from the cluster. The parameters map to both https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#DeleteOptions and https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ListOptions

Parameters:

Name	Type	Description	Default
name	str	Name for the resource to delete.	required
namespace	str | None	Optional namespace for the resource. Defaults to None	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
grace_period_seconds	int | None	Optional time to wait for graceful termination before deleting the resource. Defaults to None.	None
propagation_policy	str | None	Optional DeletionPropagation decides how a deletion propagates to dependents of the object. See https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#DeletionPropagation for more information. Defaults to None.	None
ignore_store_read_error	bool | None	Optional override to force successful deletion even if there is an etcd store error. Defaults to None.	None
extra_delete_options_kwargs	dict[str, Any] | None	Optional dictionary containing more DeleteOptions parameters. Defaults to None.	None
resource_version	str | None	Optional resourceVersion to fetch. Maps to the resourceVersion of the ObjectList object. Defaults to None.	None
resource_version_match	str | None	Optional regex string for filtering returned resources. Defaults to None.	None
label_selector	str | None	Optional label selector to filter returned resources. Defaults to None.	None
field_selector	str | None	Optional field selector to filter returned resources. Defaults to None.	None
timeout	int | None	Optional server timeout for the request. Defaults to None.	None
limit	int | None	Optional max number of resources returned. Defaults to None.	None
extra_list_options_kwargs	dict[str, Any] | None	Optional dictionary containing more ListOption parameters. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

get(name=None, namespace=None, resource_version=None, extra_options_kwargs=None, subresources=None, **kwargs)

Get an object from the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#GetOptions

Parameters:

Name	Type	Description	Default
name	str | None	The name of the resource to fetch. None is Deprecated. Defaults to None.	None
namespace	str | None	Optional namespace for the resource. Defaults to None.	None
resource_version	str | None	Optional resourceVersion to fetch. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more GetOption parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The object from the cluster as a dictionary

list(namespace=None, limit=None, resource_version=None, resource_version_match=None, label_selector=None, field_selector=None, timeout=None, continue_req=None, extra_options_kwargs=None, **kwargs)

List an object from the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ListOptions

Parameters:

Name	Type	Description	Default
namespace	str | None	Optional namespace for the resource. Defaults to None.	None
resource_version	str | None	Optional resourceVersion to fetch. Maps to the resourceVersion of the ObjectList object. Defaults to None.	None
resource_version_match	str | None	Optional regex string for filtering returned resources. Defaults to None.	None
label_selector	str | None	Optional label selector to filter returned resources. Defaults to None.	None
field_selector	str | None	Optional field selector to filter returned resources. Defaults to None.	None
timeout	int | None	Optional server timeout for the request. Defaults to None.	None
limit	int | None	Optional max number of resources returned. Defaults to None.	None
continue_req	str | None	Optional continue token to use to iterate over more results. Used with limit keywarg. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more ListOption parameters. Defaults to None.	None
subresources	list[str] | None	Optional subresource of an object to get. Defaults to None.	required
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The ObjectList object from the cluster as a dictionary e.g. use .get("items") to get list of resources

patch(name, patch_type, patch_data, namespace=None, dry_run=None, field_manager=None, field_validation=None, force=None, extra_options_kwargs=None, subresources=None, **kwargs)

Patch an object in the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#PatchOptions

Parameters:

Name	Type	Description	Default
name	str	Name of the object to patch	required
patch_type	str	Type of patch to use. See https://pkg.go.dev/k8s.io/apimachinery/pkg/types#PatchType for available options	required
patch_data	SourceObjectType	The raw patch data to use	required
resource	SourceObjectType	The resource to deploy	required
namespace	str | None	Optional namespace for the resource. Defaults to None or namespace in the provided resources.	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
field_manager	str | None	Optional field manager string to use to manage resource fields. Defaults to None.	None
force	bool | None	If the patch should be forced ignoring field_manager. Defaults to None.	None
field_validation	str | None	Optional fieldValidation instructs the server on how to handle objects in the request containing unknown or duplicate fields. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more PatchOptions parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The patched object from the cluster in a dictionary

update(resource, namespace=None, dry_run=None, field_manager=None, field_validation=None, extra_options_kwargs=None, subresources=None, **kwargs)

Update an object in the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#UpdateOptions

Parameters:

Name	Type	Description	Default
resource	SourceObjectType	The resource to deploy	required
namespace	str | None	Optional namespace for the resource. Defaults to None or namespace in the provided resources.	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
field_manager	str | None	Optional field manager string to use to manage resource fields. Defaults to None.	None
field_validation	str | None	Optional fieldValidation instructs the server on how to handle objects in the request containing unknown or duplicate fields. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more CreateOption parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The updated object from the cluster in a dictionary

update_status(resource, namespace=None, dry_run=None, field_manager=None, field_validation=None, extra_options_kwargs=None, subresources=None, **kwargs)

Update the status object in the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#UpdateOptions

Parameters:

Name	Type	Description	Default
resource	SourceObjectType	The resource to deploy	required
namespace	str | None	Optional namespace for the resource. Defaults to None or namespace in the provided resources.	None
dry_run	list[str] | None	Optional List of string dryrruns to use. Valid values can be gathered from the golang docs. Defaults to None.	None
field_manager	str | None	Optional field manager string to use to manage resource fields. Defaults to None.	None
field_validation	str | None	Optional fieldValidation instructs the server on how to handle objects in the request containing unknown or duplicate fields. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more CreateOption parameters. Defaults to None.	None
subresources	list[str] | None	Subresource of an object to get. Defaults to None.	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	dict	The updated object from the cluster in a dictionary

watch(namespace=None, resource_version=None, resource_version_match=None, label_selector=None, field_selector=None, timeout=None, limit=None, continue_req=None, extra_options_kwargs=None, watcher=None, **kwargs)

Watch for events from the cluster. The parameters map to https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#WatchOptions

Parameters:

Name	Type	Description	Default
namespace	str | None	Optional namespace for the resource. Defaults to None.	None
resource_version	str | None	Optional resourceVersion to fetch. Maps to the resourceVersion of the ObjectList object. Defaults to None.	None
resource_version_match	str | None	Optional regex string for filtering returned resources. Defaults to None.	None
label_selector	str | None	Optional label selector to filter returned resources. Defaults to None.	None
field_selector	str | None	Optional field selector to filter returned resources. Defaults to None.	None
timeout	int | None	Optional server timeout for the request. Defaults to None.	None
limit	int | None	Optional max number of resources returned. Defaults to None.	None
continue_req	str | None	Optional continue token to use to iterate over more results. Used with limit keywarg. Defaults to None.	None
extra_options_kwargs	dict[str, Any] | None	Optional dictionary containing more ListOption parameters. Defaults to None.	None
subresources	list[str] | None	Optional subresource of an object to get. Defaults to None.	required
watcher	Watch | None	Optional Watch object to use as the watcher interface. Users can use this to stop the event stream during or outside of iteration	None
**kwargs		Unused kwargs for compatibility	{}

Returns:

Name	Type	Description
dict	Watch	The ObjectList object from the cluster as a dictionary e.g. use .get("items") to get list of resources

Watch

Watch is an iterator that yields events streamed from the cluster

__init__(interface=None)

Initialize the Watch instance with a given wrapped interface

Parameters:

Name	Type	Description	Default
interface	WrappedWatchInterface | None	The interface to yield events from. Defaults to None.	None

__iter__()

Complete implementation of a python iterator

Returns:

Name	Type	Description
Watch	Watch	Itself to iterate

__next__()

Return the next event from the cluster. These events are dictionaries in the format of json encoded apimachinery Events. You can find more information here: https://pkg.go.dev/k8s.io/apimachinery/pkg/watch#Event

Returns:

Name	Type	Description
dict	dict	The event data

stop()

Stop streaming events from the cluster

kubernetes_lite.envtest

This module contains a pythonic wrapper around the https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest EnvTest object

EnvTest

EnvTest is a wrapper around the golang EnvTest object provided by https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest. This class exposes methods to start and stop the server as well as fetch a raw kubeconfig or client object. This class can also handle calling setup-envtest to download the required binaries and create the path.

To configure the underyling golang EnvTestEnvironment checkout the environmental variables exposed by EnvTest: https://book.kubebuilder.io/reference/envtest.html#environment-variables

env cached property

Return the underlying golang EnvTestEnvironment object. Must be called after starting the server

Returns:

Name	Type	Description
EnvTestEnvironment	EnvTestEnvironment	The underlying golang object for this instance

__init__(log=None)

Initialize the EnvTest object and create an event to ensure the server isn't shutdown multiple times

Parameters:

Name	Type	Description	Default
log	logger | None	Optional logger to provide. Defaults to None	None

client()

Fetch a dynamic client object for interacting with the EnvTest server. Must be called after start()

Returns:

Name	Type	Description
DynamicClient	DynamicClient	A client to interact with the server

config()

Fetch a kubeconfig object for the given EnvTest server. Must be called after start()

Returns:

Name	Type	Description
BytesIO	BytesIO	The raw byte stream of the kube object

start(auto_setup=True)

Construct and start the EnvTestEnvironment object. Can optionally run setupenv-test to download the correct kube bins.

Parameters:

Name	Type	Description	Default
auto_setup	bool	If setup-envtest should be ran to fetch the local path. Defaults to True.	True

Returns:

Name	Type	Description
BytesIO	BytesIO	A raw kube_config for interacting with the cluster.

stop()

Stop the envtest server if it hasn't already been stopped

kubernetes_lite.setup_envtest

This module contains functions to run setup-envtest. See https://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest for more information regarding arguments

internal_run_setup_envtest_command(*args, stdin=b'')

This function runs the underlying setup_envtest command with a provided args and stdin.

Parameters:

Name	Type	Description	Default
*args	list[str]	The arguments to pass to setup-envtest	()
stdin	bytes	The stdin data to send to setup-envtest. Defaults to b"".	b''

Returns:

Name	Type	Description
SetupEnvTestResult	SetupEnvTestResult	A parsed dataclass containing the returned error and captured stdout/stderr

run_setup_envtest_command(log=None)

Function to handle running the setup_envtest command as if the user ran this module directly. It handles reading from the process args/stdin and passing them to internal_run_setup_envtest_command. This function handles logging the result and exiting with the correct exit code

Parameters:

Name	Type	Description	Default
log	Logger | None	Logger to use for printing setup_envtest messages. Defaults to None.	None