Adding Resources

OpenShift Python Wrapper provides tools to easily add support for new Kubernetes and OpenShift resources. You can use the automated class generator or add resources manually.

Using the Class Generator (Recommended)

The class generator automatically creates resource classes from Kubernetes API schemas.

Installation

The class generator is included when you install openshift-python-wrapper:

uv tool install openshift-python-wrapper

Or with pip:

python3 -m pip install openshift-python-wrapper

Shell Completion

Add shell completion to your shell configuration (~/.bashrc or ~/.zshrc):

if type class-generator > /dev/null; then 
  eval "$(_CLASS_GENERATOR_COMPLETE=zsh_source class-generator)"
fi

Basic Usage

Generate a class for a specific resource kind:

class-generator --kind Pod

Generate multiple resources at once:

class-generator --kind Pod,Service,Deployment

Preview the generated code without writing files:

class-generator --kind Pod --dry-run

File Naming

The generator creates files in ocp_resources/ with snake_case naming:

Pod → pod.py
CDIConfig → cdi_config.py
VirtualMachine → virtual_machine.py

Important: Review the generated filename to ensure it follows Python naming conventions.

Handling Duplicate Kinds

Some resources share the same kind but have different API groups. The generator handles this by including the API group in the filename:

class-generator --kind DNS

This creates two files:

dns_config_openshift_io.py (from config.openshift.io)
dns_operator_openshift_io.py (from operator.openshift.io)

Overwriting Existing Resources

When updating or regenerating resources, use the --overwrite flag with --backup to safely preserve the original:

class-generator --kind Pod --overwrite --backup

Backups are stored in .backups/backup-YYYYMMDD-HHMMSS/ with the original directory structure preserved.

Batch Regeneration

Regenerate all resources with backups:

class-generator --regenerate-all --backup

Discovering Missing Resources

The class generator can automatically discover resources in your cluster that don’t have wrapper classes yet.

Basic Discovery

Generate a coverage report showing missing resources:

class-generator --discover-missing

Example Output

Resource Coverage Report

╭─────────────────────────── Coverage Statistics ────────────────────────────╮
│ Total Discovered Resources: 397                                             │
│ Total Implemented: 197                                                      │
│ Covered Resources: 172                                                      │
│ Total Missing: 225                                                          │
│ Coverage Percentage: 43.32%                                                 │
╰─────────────────────────────────────────────────────────────────────────────╯

Missing Resources (sorted by priority)

┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Priority   ┃ Kind            ┃ API Version          ┃ Namespaced ┃ Command                       ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ CORE       │ Binding         │ v1                   │ Yes        │ class-generator -k Binding    │
│ HIGH       │ PodTemplate     │ v1                   │ Yes        │ class-generator -k PodTemplate│
└────────────┴─────────────────┴──────────────────────┴────────────┴───────────────────────────────┘

Tip: You can generate multiple resources at once:
  class-generator -k Binding,PodTemplate

Priority Levels

CORE: Essential Kubernetes resources (v1 API group)
HIGH: Common workload resources (apps/v1, batch/v1)
MEDIUM: Platform-specific resources (OpenShift, operators)
LOW: Custom resources and less common APIs

Discovery Options

JSON output for CI/CD integration:

class-generator --discover-missing --json

Force fresh discovery (bypass cache):

class-generator --discover-missing --no-cache

Caching

Discovery results are cached for 24 hours in:

~/.cache/openshift-python-wrapper/discovery_cache.json

This improves performance for repeated discoveries.

Updating Resource Schemas

Resource schemas can be updated from a connected Kubernetes/OpenShift cluster.

Prerequisites

Connected to a Kubernetes/OpenShift cluster
oc or kubectl
Admin access to the cluster

Full Schema Update

Update all resource schemas from your cluster:

class-generator --update-schema

This fetches all resource schemas and updates the local cache. When connected to an older cluster, existing schemas are preserved and only missing resources are added.

Single Resource Schema Update

Update the schema for a specific resource:

class-generator --update-schema-for VirtualMachine

This is useful when:

Connected to an older cluster but need a specific CRD
A new operator was installed
You want to refresh one resource without a full update

After updating the schema, regenerate the class:

class-generator --kind VirtualMachine --overwrite

--update-schema and --update-schema-for are mutually exclusive. Use one or the other, not both.

Manual Resource Creation

If you need more control or the generator doesn’t fit your needs, you can create resources manually.

Resource File Structure

Create a new file in ocp_resources/ following these rules:

File naming: Use snake_case (e.g., config_map.py for ConfigMap)
Class naming: Match the resource kind exactly
Inheritance:
- Cluster-scoped resources: inherit from Resource
- Namespaced resources: inherit from NamespacedResource

Example: Namespaced Resource

ocp_resources/config_map.py

from typing import Any

from ocp_resources.resource import NamespacedResource


class ConfigMap(NamespacedResource):
    """
    ConfigMap resource.
    
    API reference:
    https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1/
    """

    api_group = NamespacedResource.ApiGroup.CORE_V1

    def __init__(
        self,
        name: str | None = None,
        namespace: str | None = None,
        data: dict[str, str] | None = None,
        **kwargs: Any,
    ) -> None:
        super().__init__(name=name, namespace=namespace, **kwargs)
        self.data = data

    def to_dict(self) -> dict[str, Any]:
        res = super().to_dict()
        if self.data:
            res["data"] = self.data
        return res

Example: Cluster-scoped Resource

ocp_resources/backup.py

from typing import Any

from ocp_resources.resource import Resource


class Backup(Resource):
    """
    Backup resource from velero.io.
    
    API reference:
    https://velero.io/docs/main/api-types/backup/
    """

    api_group = Resource.ApiGroup.VELERO_IO

    def __init__(
        self,
        name: str | None = None,
        included_namespaces: list[str] | None = None,
        storage_location: str | None = None,
        **kwargs: Any,
    ) -> None:
        super().__init__(name=name, **kwargs)
        self.included_namespaces = included_namespaces
        self.storage_location = storage_location

    def to_dict(self) -> dict[str, Any]:
        res = super().to_dict()
        if self.yaml_file:
            return res

        spec = res.setdefault("spec", {})
        if self.included_namespaces:
            spec["includedNamespaces"] = self.included_namespaces
        if self.storage_location:
            spec["storageLocation"] = self.storage_location
        return res

Required Components

API Group: Define under Resource.ApiGroup or NamespacedResource.ApiGroup
API Reference: Include a link to the official API documentation
__init__ method: Define required and optional parameters
to_dict method: Convert the resource to a dictionary for API calls

Best Practices

Add type hints to all methods and parameters
Include docstrings explaining the resource purpose
Link to official API documentation
Only include required and commonly used parameters in __init__
Handle optional parameters with None defaults

Adding Tests

After creating a resource, add tests using the test generator:

class-generator --kind YourResource --add-tests

Or use the standalone test generator:

uv run tests/scripts/generate_pytest_test.py --kind YourResource

See Testing for more details.

Verification

After adding a resource:

Run pre-commit checks:
```
prek run --all-files
```

Run tests:

uv run --group tests pytest tests/test_resources/test_your_resource.py

Test in your environment:

from ocp_resources.your_resource import YourResource

resource = YourResource(name="test", namespace="default")
resource.deploy()

Getting Help

For help with the class generator:

class-generator --help

For questions or issues, open an issue on GitHub.

Development

Using the Class Generator (Recommended)

Installation

Shell Completion

Basic Usage

File Naming

Handling Duplicate Kinds

Overwriting Existing Resources

Batch Regeneration

Discovering Missing Resources

Basic Discovery

Example Output

Priority Levels

Discovery Options

Caching

Updating Resource Schemas

Prerequisites

Full Schema Update

Single Resource Schema Update

Manual Resource Creation

Resource File Structure

Example: Namespaced Resource

Example: Cluster-scoped Resource

Required Components

Best Practices

Adding Tests

Verification

Getting Help

Build docs developers (and LLMs) love

Development

​Using the Class Generator (Recommended)

​Installation

​Shell Completion

​Basic Usage

​File Naming

​Handling Duplicate Kinds

​Overwriting Existing Resources

​Batch Regeneration

​Discovering Missing Resources

​Basic Discovery

​Example Output

​Priority Levels

​Discovery Options

​Caching

​Updating Resource Schemas

​Prerequisites

​Full Schema Update

​Single Resource Schema Update

​Manual Resource Creation

​Resource File Structure

​Example: Namespaced Resource

​Example: Cluster-scoped Resource

​Required Components

​Best Practices

​Adding Tests

​Verification

​Getting Help

Build docs developers (and LLMs) love

Using the Class Generator (Recommended)

Installation

Shell Completion

Basic Usage

File Naming

Handling Duplicate Kinds

Overwriting Existing Resources

Batch Regeneration

Discovering Missing Resources

Basic Discovery

Example Output

Priority Levels

Discovery Options

Caching

Updating Resource Schemas

Prerequisites

Full Schema Update

Single Resource Schema Update

Manual Resource Creation

Resource File Structure

Example: Namespaced Resource

Example: Cluster-scoped Resource

Required Components

Best Practices

Adding Tests

Verification

Getting Help