Resources preloading

Instead of defining resources one by one in tests, the resource definitions can be loaded from prepared data files. These files are generated from a real Kubernetes cluster and contain the full API resource discovery information.

Warning

The data format is opaque and should not be interpreted. Store and use the files exactly as generated by kmock fetch resources. The format may change at any time without warning, but backward compatibility with files generated in older formats will always be maintained.

Loading resources

There are three ways to load resource definitions into the kmock.resources associative array.

From a file path

Use load_path() to load resource definitions from a file on disk. Gzip, bzip2, and zstd (Python 3.14+) compressed files are supported automatically based on the file extension:

import kmock

async def test_with_resource_file(kmock: kmock.KubernetesScaffold) -> None:
    kmock.resources.load_path('path/to/resources.dat')

    # Or compressed:
    kmock.resources.load_path('path/to/resources.gz')
    kmock.resources.load_path('path/to/resources.bz2')
    kmock.resources.load_path('path/to/resources.zst')  # Python 3.14+

Both string paths and pathlib.Path objects are accepted.

From a data blob

Use load_data() to load resource definitions from a string or bytes object, for example when the resource file is bundled with your own package:

import gzip
import importlib.resources

import kmock

async def test_with_raw_data(kmock: kmock.KubernetesScaffold) -> None:
    data = importlib.resources.read_binary('mypkg', 'resources.gz')
    kmock.resources.load_data(gzip.decompress(data))

From bundled data

The simplest way is to use load_bundled() to load the resource definitions bundled with the package. This file is pre-built from a recent K3s cluster and contains the standard Kubernetes builtins:

import kmock

async def test_with_bundled_resources(kmock: kmock.KubernetesScaffold) -> None:
    kmock.resources.load_bundled()

    # Standard resources are now available for discovery:
    resp = await kmock.get('/api/v1')
    data = await resp.read()
    assert data['kind'] == 'APIResourceList'

The bundled data contains only the standard Kubernetes built-in resources (core API, apps, batch, autoscaling, policy, and the *.k8s.io groups). It does not include any third-party CRDs or custom resources. It might also be outdated or incomplete. For anything beyond a quick “good enough” setup, generate your own resource file (see below).

Multiple calls to any of the loading methods are additive: the resources accumulate. If the same resource appears twice, the last definition wins.

Generating resource files

The kmock fetch resources CLI command connects to a Kubernetes cluster and dumps the API resource discovery information to a file.

Running the command

The command uses the current kubeconfig context. It relies on the kubernetes client library for API authentication, which covers all the sophisticated authentication methods (tokens, certificates, external auth providers, etc.). Since the kubernetes library is too heavy to include as a default runtime dependency, it is available as an optional extra:

pip install kmock[fetch]

Fetch resources and write to a file:

kmock fetch resources -o resources.dat

The output format is determined by the file extension. Use .gz, .bz2, or .zst (Python 3.14+) extensions for compressed output:

kmock fetch resources -o resources.gz
kmock fetch resources -o resources.bz2
kmock fetch resources -o resources.zst

Omit -o to write to stdout:

kmock fetch resources > resources.dat

Only the fields used by the loader are stored in the output file. Unnecessary fields from the API responses (such as storageVersionHash) are stripped automatically.

Filtering groups

By default, only the standard Kubernetes groups are included: the core API (v1), apps, autoscaling, batch, policy, and all *.k8s.io groups. Third-party CRDs and custom groups are excluded.

Use --include/-i to include additional groups or specific group/versions:

# Include all versions of the kopf.dev group:
kmock fetch resources -o resources.dat --include=kopf.dev

# Include only a specific version:
kmock fetch resources -o resources.dat --include=kopf.dev/v1

Use --exclude/-x to exclude groups or specific group/versions:

# Exclude the metrics group:
kmock fetch resources -o resources.dat --exclude=metrics.k8s.io

# Exclude a specific version:
kmock fetch resources -o resources.dat --exclude=autoscaling/v1

Use --include=* to include everything from the cluster:

kmock fetch resources -o resources.dat --include=*

The filters support simple glob patterns and are applied sequentially from left to right, so they can be combined:

# Include all kopf.dev versions except v2:
kmock fetch resources -o resources.dat --include=kopf.dev --exclude=kopf.dev/v2

# Include everything except third-party groups:
kmock fetch resources -o resources.dat --include=* --exclude=helm.cattle.io --exclude=traefik.io