openshift-template-client 0.1.0__py3-none-any.whl

openshift_template_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,415 @@
+Metadata-Version: 2.4
+Name: openshift-template-client
+Version: 0.1.0
+Summary: Small Python client for OpenShift templates and their resources
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: kubernetes<35,>=30
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.9; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+
+# openshift-template-client
+
+A minimal synchronous Python library for a separate mini scheduler to process
+existing OpenShift Templates and create, inspect, or delete their namespaced resources.
+Python 3.9+; `kubernetes>=30,<35` is the only direct runtime dependency.
+
+It uses Kubernetes `DynamicClient` discovery, including installed APIs such as
+KubeVirt `VirtualMachine`. OpenShift performs parameter substitution; no local
+template engine or `oc`/`kubectl` subprocess is used. Scheduling stays in the
+caller. Importing the package does not authenticate or contact a cluster.
+
+## Install
+
+After the first successful PyPI release, install remotely without cloning:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install openshift-template-client
+```
+
+To select a particular published release, use
+`python -m pip install 'openshift-template-client==0.1.0'` (once `0.1.0` is
+published). To upgrade later, use `python -m pip install --upgrade
+openshift-template-client`. Import the installed package as `openshift_templates`.
+
+Before publishing to PyPI, or to use the GitHub source, install directly from
+the repository after pushing the code there. This requires Git:
+
+```bash
+python -m pip install 'openshift-template-client @ git+https://github.com/Ravid-Amar/openshift-template-client.git@main'
+```
+
+Replace `@main` with a pushed release tag such as `@v0.1.0` to select that
+revision. For development from a local clone:
+
+```bash
+git clone https://github.com/Ravid-Amar/openshift-template-client.git
+cd openshift-template-client
+python -m pip install -e '.[dev]'
+```
+
+Both pip/venv and the existing `src/` layout are supported. No uv migration is
+required. See [START_HERE.md](START_HERE.md) for wheelhouse installation offline.
+
+Pushing a `v*` tag runs the [PyPI publishing workflow](.github/workflows/publish.yml).
+The tag must equal `v` plus the version in `pyproject.toml`. See
+[Publishing releases](docs/publishing.md) for the one-time GitHub/PyPI setup and
+release commands. PyPI installation becomes available after a successful upload;
+creating this workflow alone does not publish a package.
+
+## Local kubeconfig: create, then delete after restart
+
+The `worker-template` Template must already exist in `infra`. The target
+namespace `workers` and required namespaced APIs must also exist. Adapt the
+parameter names to your Template, including explicit values for every unresolved
+generator. This example assumes `VM_NAME` and `IMAGE_TAG` are its parameters.
+
+```python
+import openshift_templates as ocp
+
+api = ocp.connect(kubeconfig="/path/to/kubeconfig", context="dev", request_timeout=(5, 30))
+try:
+    refs = ocp.create(
+        "worker-template",
+        {"VM_NAME": "worker-001", "IMAGE_TAG": "1.2.3"},
+        namespace="workers",
+        template_namespace="infra",
+        api=api,
+        request_timeout=(5, 30),
+    )
+finally:
+    api.client.close()
+```
+
+Later, in a fresh process, use the same template and inputs. No create result,
+resource inventory, or discovery cache needs to be retained:
+
+```python
+import openshift_templates as ocp
+
+api = ocp.connect(kubeconfig="/path/to/kubeconfig", context="dev")
+try:
+    deleted = ocp.delete(
+        "worker-template",
+        {"VM_NAME": "worker-001", "IMAGE_TAG": "1.2.3"},
+        namespace="workers",
+        template_namespace="infra",
+        api=api,
+    )
+finally:
+    api.client.close()
+```
+
+`connect()` without kubeconfig/context uses the Kubernetes client's usual local
+kubeconfig search and current context. Omitting `api` from an operation opens a
+local client and closes it on success or failure. Injected clients remain open
+for reuse; their owner must close `api.client`. `connect()` closes its transport
+if discovery fails. TLS certificate verification defaults to `True`; configure
+the cluster CA in kubeconfig. To disable verification explicitly, use
+`connect(verify_ssl=False)` and pass that client as `api` to operations. This
+setting applies to discovery and all resource requests, with either auth mode
+(including `connect(in_cluster=True, verify_ssl=False)`):
+
+```python
+params = {"VM_NAME": "worker-001", "IMAGE_TAG": "1.2.3"}
+api = ocp.connect(kubeconfig="/path/to/kubeconfig", context="dev", verify_ssl=False)
+try:
+    objects = ocp.get(
+        "worker-template", params, namespace="workers", template_namespace="infra", api=api
+    )
+finally:
+    api.client.close()
+```
+
+With verification disabled, the server certificate is not authenticated.
+Kubeconfig updates and HTTP debug output are disabled by `connect()`.
+
+## In-cluster ServiceAccount
+
+Inside a pod with ServiceAccount credentials and cluster CA mounted, use:
+
+```python
+import openshift_templates as ocp
+
+params = {"VM_NAME": "worker-002", "IMAGE_TAG": "1.2.3"}
+api = ocp.connect(in_cluster=True)
+try:
+    ocp.create("worker-template", params, namespace="workers", template_namespace="infra", api=api)
+finally:
+    api.client.close()
+
+# Later, including in a new pod/process with the same stored job inputs:
+api = ocp.connect(in_cluster=True)
+try:
+    ocp.delete("worker-template", params, namespace="workers", template_namespace="infra", api=api)
+finally:
+    api.client.close()
+```
+
+Do not combine `in_cluster=True` with kubeconfig/context. Grant this
+ServiceAccount the permissions below in the source and target namespaces.
+
+## Public API
+
+Import as `openshift_templates`. All operations are synchronous and have type
+hints and docstrings with parameters, returns, errors, and examples.
+
+| Function | What it does | Returns |
+| --- | --- | --- |
+| `connect()` | Loads local kubeconfig/context or in-cluster credentials and discovers APIs. Close its transport with `api.client.close()`. | A reusable `DynamicClient`. |
+| `process()` | Fetches a stored Template, overrides parameters in a copy, and asks OpenShift to render it. No resources are deployed. | Rendered manifest dictionaries. |
+| `create()` | Calls `process()`, validates every target, then applies them in order with server-side apply. `field_manager` defaults to `mini-scheduler`; conflicts are preserved. | Identity references, including returned UIDs. |
+| `get()` | Reconstructs template identities and reads the currently deployed objects in order. It takes the same template arguments as `create()`, or `resources=refs`. | Full live dictionaries, including each kind's `status` when present. |
+| `delete()` | Reconstructs template identities and deletes them in reverse order. Missing objects are already absent. It also accepts `resources=refs`. | Successful identity references. |
+
+`process`, `create`, `get`, and `delete` accept `template_name`, optional
+`parameters`, required target `namespace`, optional `template_namespace`,
+optional injected `api`, and `request_timeout`. `get`/`delete` accept either
+template inputs or `resources`, never both. Their `template_name` defaults to
+`None` to allow the reference mode; it is required when `resources` is omitted.
+Supplying neither mode is invalid. All five functions have examples
+and explanations in their docstrings; internal helper functions explain their
+single responsibility where they are defined.
+
+`template_namespace` defaults to the target `namespace` only when omitted.
+Explicitly invalid/empty namespaces fail before authentication or API requests.
+Parameters are string-keyed mappings of strings, booleans, integers, or finite
+floats; booleans become `true`/`false`, other scalar values become strings.
+Unknown names and `None` values are errors. Unspecified Template defaults remain
+intact. Overrides remove the parameter's `generate` and `from` fields in a copy;
+the stored Template is never changed.
+
+Each operation accepts positive seconds or a `(connect, read)` seconds tuple;
+the default is `(10, 60)`. This is a per-request timeout, not a whole-operation
+deadline. `connect(request_timeout=...)` configures discovery and direct client
+calls. Pass the operation's `request_timeout` separately for its Template GET,
+processing POST, and resource mutations. With an injected client, discovery uses
+that client's configuration. Clients constructed by `connect()` disable
+transport retries; injected clients should also disable mutation retries.
+
+`process(..., for_delete=True)` remains accepted for compatibility. Deterministic
+parameter checks now apply regardless of that flag, including processing only.
+To inspect rendering:
+
+```python
+objects = ocp.process(
+    "worker-template", params, namespace="workers", template_namespace="infra", api=api
+)
+```
+
+### Resource UIDs and optional deletion protection
+
+OpenShift assigns each resource a UID and stores it in the live object's
+`metadata.uid`. `create()` copies that UID from the server-side apply response
+into its returned references. The package does not save those references or UIDs
+to disk; retaining them is optional.
+
+Template-based deletion works after a pod/process restart using the same job
+inputs. It reprocesses the Template and deletes by name and namespace, without
+fetching the live resources or their UIDs. No saved `create()` result is needed.
+
+The optional reference mode skips Template processing and uses any supplied UID
+as a deletion precondition:
+
+```python
+import openshift_templates as ocp
+
+params = {"VM_NAME": "worker-001", "IMAGE_TAG": "1.2.3"}
+api = ocp.connect()  # Or connect(in_cluster=True) in a pod.
+try:
+    refs = ocp.create(
+        "worker-template", params, namespace="workers", template_namespace="infra", api=api
+    )
+    # template_name defaults to None here because resources supplies the identities.
+    # A saved UID protects against deleting a replacement object with the same name.
+    ocp.delete(namespace="workers", resources=refs, api=api)
+finally:
+    api.client.close()
+```
+
+If a live object's UID differs from the supplied UID, the server rejects that
+deletion with 409, exposed through `OperationError`. References without UIDs are
+also accepted and delete by name/namespace. Omit `template_name`, `parameters`,
+and `template_namespace` when passing `resources`. An empty reference list is a
+valid no-op. A UID embedded in a rendered Template is never used as a deletion
+precondition.
+
+`get()` returns current live UIDs, but reading one before deletion cannot prove
+that it belongs to the original object: a replacement may already exist. Only
+retaining the original UID provides that additional identity protection.
+
+## Inspect deployed resources
+
+Use the same job inputs after restart, or pass `resources=refs` from create.
+`get()` reads the main resource endpoints, including KubeVirt VirtualMachines;
+it does not poll, wait, or decide whether a workload is ready.
+
+```python
+import openshift_templates as ocp
+
+api = ocp.connect()  # Or connect(in_cluster=True) in a pod.
+try:
+    objects = ocp.get(
+        "worker-template",
+        {"VM_NAME": "worker-001", "IMAGE_TAG": "1.2.3"},
+        namespace="workers",
+        template_namespace="infra",
+        api=api,
+    )
+    for obj in objects:
+        print(obj["kind"], obj["metadata"]["name"], obj.get("status", {}))
+finally:
+    api.client.close()
+```
+
+These are live responses, unlike the desired manifests from `process()`. A kind
+such as ConfigMap may have no `status`. Read errors, including 404 for a missing
+resource, 403, and timeouts, propagate immediately; a failed call returns no
+partial list. Responses include the full object, so avoid logging Secret objects.
+Each object is read sequentially; the list is not an atomic cluster snapshot.
+
+## Stateless replay and namespace boundaries
+
+- Both create and template-based delete reject unresolved parameter generators,
+  even if a generator appears unrelated to an object's name. Supply explicit
+  values, or use a nonempty fixed default already in the Template. No random
+  value is regenerated by these operations.
+- Every rendered object needs a stable `metadata.name`. `metadata.generateName`
+  is rejected even when a name is also supplied.
+- All rendered targets are discovered and validated before any resource apply
+  or delete. Only namespaced resources in the requested target namespace are
+  accepted. An omitted/empty manifest namespace becomes the target namespace;
+  another namespace, or any cluster-scoped kind, is rejected. Namespace and CRD
+  creation are outside this library.
+- Stateless replay depends on compatible Template revisions and the same
+  parameters reproducing identical API resource kinds, names, and namespaces.
+  Keep that revision available. Renaming/removing an object can leave the old
+  object undiscoverable by replay. Apply does not prune removed objects.
+- Use unique names per scheduler job. Manage shared resources separately.
+  Template-based deletion is by name: it can delete a replacement with the same
+  identity and provides no original-UID protection after restart.
+
+For core `v1` Secrets, create converts UTF-8 `stringData` to base64 `data` before
+server-side apply, preserving existing keys and giving `stringData` precedence
+on collisions. This follows the API's merge behavior and avoids the documented
+[Secret stringData limitations with server-side apply](https://kubernetes.io/docs/concepts/configuration/secret/#working-with-secrets).
+Normalization uses only the standard library, works on copies, and does not
+change `process()` output. Base64 is not encryption.
+
+## Failures and completion
+
+Invalid arguments and unsafe rendered identities raise `ValueError`. Failures
+before resource mutations (authentication, discovery, Template GET/POST,
+processing timeouts) propagate directly from the Kubernetes client/transport.
+Other schema validation remains the server's responsibility.
+
+Mutation failures raise `OperationError`. Its `.operation` is `Apply` or `Delete`,
+`.resources` contains successful identity references, and `.failures` contains
+`(reference, original_exception)` pairs. Apply stops at its first failure;
+delete attempts every validated target in reverse order. Only an individual
+delete's 404 is a successful no-op. Permission errors (403), field/UID conflicts
+(409), validation errors, and timeouts remain visible. No rollback or automatic
+mutation retry is performed.
+
+```python
+try:
+    ocp.create("worker-template", params, namespace="workers", template_namespace="infra", api=api)
+except ocp.OperationError as error:
+    accepted = error.resources
+    failed_references = [ref for ref, exception in error.failures]
+    # Let your scheduler decide how to reconcile the outcome.
+```
+
+Multi-object operations are not transactional. A mutation timeout has an unknown
+outcome: the server may have accepted it. Success means API acceptance, not VM
+readiness or completed background deletion. The package does not log tokens,
+parameter values, or rendered Secrets. References and the `OperationError`
+message contain identities only; raw exceptions/tracebacks may include server
+response bodies, so avoid logging them wholesale.
+
+## Namespace-scoped permissions
+
+Grant only the API groups/kinds actually used by your Templates. Ordinary API
+discovery access is needed; it grants no cluster-scoped mutation permission.
+`get()` additionally needs target resource `get` permission. No operation needs
+target resource `list` or `watch` permission.
+
+| Namespace | API group / resource | Verbs |
+| --- | --- | --- |
+| Source (`infra`) | `template.openshift.io` / `templates` | `get` (can restrict to the Template's name) |
+| Target (`workers`) | `template.openshift.io` / `processedtemplates` | `create` |
+| Target (`workers`) | Each rendered resource, e.g. core `configmaps`, `secrets`; `kubevirt.io` / `virtualmachines` | `create`, `patch`, `delete`; add `get` for inspection |
+
+Example Roles for a Template producing ConfigMaps, Secrets, and VirtualMachines:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: worker-template-reader
+  namespace: infra
+rules:
+  - apiGroups: [template.openshift.io]
+    resources: [templates]
+    resourceNames: [worker-template]
+    verbs: [get]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: worker-template-manager
+  namespace: workers
+rules:
+  - apiGroups: [template.openshift.io]
+    resources: [processedtemplates]
+    verbs: [create]
+  - apiGroups: [""]
+    resources: [configmaps, secrets]
+    verbs: [create, patch, delete, get]
+  - apiGroups: [kubevirt.io]
+    resources: [virtualmachines]
+    verbs: [create, patch, delete, get]
+```
+
+Have namespace owners bind each Role with a RoleBinding in its namespace to
+your user or the pod's ServiceAccount (specify the ServiceAccount's actual
+namespace, even for a binding in another namespace). The library does not create
+these Roles/bindings. No ClusterRole, CRD installation, or cluster-admin grant is
+required by this workflow. KubeVirt must already be installed if used.
+
+## Development and validation
+
+```bash
+python -m pytest
+python -m ruff check .
+python -m ruff format --check .
+python -m build
+```
+
+Tests block real credential loading/network access and mock transport while
+exercising the real DynamicClient's HTTP construction. They cover replay with a
+fresh client, optional UID preconditions, live status reads, namespace/scope
+boundaries, generators, reverse/repeated deletion, SSA conflicts, partial
+failures, timeouts (including discovery), Secret
+normalization, and client ownership. Builds use `pyproject.toml` and produce a
+wheel and sdist; isolated builds may fetch build dependencies.
+
+A clean-environment wheel import can be checked without cluster credentials:
+
+```bash
+python -m venv /tmp/openshift-template-wheel-check
+/tmp/openshift-template-wheel-check/bin/python -m pip install dist/*.whl
+/tmp/openshift-template-wheel-check/bin/python -I -c 'import openshift_templates'
+```
+
+For a fully offline install/build, prepare a wheelhouse as described in
+[START_HERE.md](START_HERE.md). Python 3.9 syntax compatibility is maintained;
+runtime checks here use Python 3.12 and kubernetes 34.1.0. Actual Python 3.9
+execution and live OpenShift validation remain target-environment checks.
+Live checks should confirm deployed-version processing, RBAC, SSA/Secret and
+KubeVirt behavior, and admission/finalizer effects. See
+[docs/api-notes.md](docs/api-notes.md) for endpoint details and official sources.

openshift_template_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+openshift_templates/__init__.py,sha256=ZK0J32APVDcjVvipkZqutMTS4HWyo7hSxDnAXKQg3O0,235
+openshift_templates/_client.py,sha256=GIyV5TuHRs9sgpIXpMy48k3DWMyKqOcyApAtzs9x3rQ,23410
+openshift_templates/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openshift_template_client-0.1.0.dist-info/METADATA,sha256=aBHd1TUYqG3rUnFyEqL7TNW3v1q_N1Syf_iIGINFAUE,18578
+openshift_template_client-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+openshift_template_client-0.1.0.dist-info/top_level.txt,sha256=vPgu4Pf-f8OuqodogZgz9fFRMe7pi5veZVGGi5FoUvE,20
+openshift_template_client-0.1.0.dist-info/RECORD,,

openshift_template_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openshift_template_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openshift_templates

openshift_templates/__init__.py

@@ -0,0 +1,5 @@
+"""Small OpenShift Template client; see README.md for usage and limitations."""
+
+from ._client import OperationError, connect, create, delete, get, process
+
+__all__ = ["OperationError", "connect", "create", "delete", "get", "process"]

openshift_templates/_client.py

@@ -0,0 +1,506 @@
+"""Synchronous OpenShift Template processing and stateless resource lifecycle."""
+
+import re
+from base64 import b64encode
+from collections.abc import Mapping
+from contextlib import contextmanager
+from copy import deepcopy
+from math import isfinite
+from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
+
+from kubernetes import client, config
+from kubernetes.dynamic import DynamicClient
+from kubernetes.dynamic.exceptions import NotFoundError
+from kubernetes.dynamic.resource import Resource
+
+API_VERSION = "template.openshift.io/v1"
+RequestTimeout = Union[float, Tuple[float, float]]
+Parameters = Mapping[str, Union[str, bool, int, float]]
+Manifest = Dict[str, Any]
+REQUEST_TIMEOUT: RequestTimeout = (10, 60)
+
+
+class OperationError(RuntimeError):
+    """Mutation failures: operation name, successful references, and (reference, error) pairs.
+
+    Messages contain identities only; original exceptions can include response bodies.
+    """
+
+    def __init__(
+        self,
+        operation: str,
+        resources: List[Manifest],
+        failures: List[Tuple[Manifest, Exception]],
+    ) -> None:
+        """Keep successful references and original failures; format an identity-only message."""
+        self.operation = operation
+        self.resources = resources
+        self.failures = failures
+        labels = [f"{ref['kind']}/{ref['metadata']['name']}" for ref, _ in failures]
+        super().__init__(f"{operation} failed for {', '.join(labels)}")
+
+
+def _validate_timeout(request_timeout: RequestTimeout) -> None:
+    """Reject invalid or unbounded timeout settings before opening a connection."""
+    values = request_timeout if isinstance(request_timeout, tuple) else (request_timeout,)
+    if (isinstance(request_timeout, tuple) and len(values) != 2) or any(
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not isfinite(value)
+        or value <= 0
+        for value in values
+    ):
+        raise ValueError("request_timeout must be positive seconds or a (connect, read) pair")
+
+
+def _validate_inputs(
+    template_name: Optional[str],
+    parameters: Optional[Parameters],
+    namespace: str,
+    template_namespace: Optional[str],
+    request_timeout: RequestTimeout,
+    resources: Optional[List[Manifest]] = None,
+) -> None:
+    """
+    Check namespaces, timeout, and either template inputs or references before connecting.
+    “DNS subdomain” describes the name’s format—it doesn’t require a real domain or DNS record.
+    """
+    namespaces = {"namespace": namespace}
+    if template_namespace is not None:
+        namespaces["template_namespace"] = template_namespace
+    for argument, value in namespaces.items():
+        if (
+            not isinstance(value, str)
+            or len(value) > 63
+            or not re.fullmatch(r"[a-z0-9](?:[-a-z0-9]*[a-z0-9])?", value)
+        ):
+            raise ValueError(f"{argument} must be a nonempty DNS label of at most 63 characters")
+    _validate_timeout(request_timeout)
+    # get/delete have two exclusive input modes. An empty reference list is valid;
+    # None selects template replay, which requires a template_name below.
+    if resources is not None:
+        if template_name is not None or parameters is not None or template_namespace is not None:
+            raise ValueError("Provide resources OR template inputs, not both")
+        if not isinstance(resources, list) or any(not isinstance(obj, dict) for obj in resources):
+            raise ValueError("resources must be a list of manifest dictionaries")
+        return
+    if (
+        not isinstance(template_name, str)
+        or len(template_name) > 253
+        or not re.fullmatch(
+            r"[a-z0-9](?:[-a-z0-9]*[a-z0-9])?(?:\.[a-z0-9](?:[-a-z0-9]*[a-z0-9])?)*", template_name
+        )
+    ):
+        raise ValueError("template_name must be a nonempty DNS subdomain")
+    if parameters is not None:
+        if not isinstance(parameters, Mapping) or any(
+            not isinstance(name, str) or not name for name in parameters
+        ):
+            raise ValueError("parameters must be a mapping with nonempty string names")
+        for name, value in parameters.items():
+            if value is None:
+                raise ValueError(f"Parameter {name} cannot be None")
+            if not isinstance(value, (str, bool, int, float)) or (
+                isinstance(value, float) and not isfinite(value)
+            ):
+                raise ValueError(
+                    f"Parameter {name} must be a string, boolean, integer, or finite float."
+                )
+
+
+def connect(
+    *,
+    in_cluster: bool = False,
+    kubeconfig: Optional[str] = None,
+    context: Optional[str] = None,
+    verify_ssl: bool = True,
+    request_timeout: RequestTimeout = REQUEST_TIMEOUT,
+) -> DynamicClient:
+    """Return a reusable DynamicClient using local kubeconfig or pod credentials.
+
+    kubeconfig/context select local credentials; in_cluster selects the ServiceAccount.
+    request_timeout is seconds or (connect, read) seconds for discovery/direct calls.
+    verify_ssl enables certificate verification by default; False disables it for
+    discovery and all requests through this client. Transport retries are disabled. The caller
+    must close api.client. Invalid settings raise ValueError; authentication and
+    API errors propagate. Discovery failures close the transport before raising.
+
+    Example: api = connect(kubeconfig="/path/to/config", context="dev")"""
+    _validate_timeout(request_timeout)
+    if in_cluster and (kubeconfig is not None or context is not None):
+        raise ValueError("in_cluster cannot be combined with kubeconfig or context")
+    configuration = client.Configuration()
+    if in_cluster:
+        config.load_incluster_config(client_configuration=configuration)
+    else:
+        config.load_kube_config(
+            config_file=kubeconfig,
+            context=context,
+            client_configuration=configuration,
+            persist_config=False,
+        )
+    configuration.verify_ssl = verify_ssl
+    configuration.debug = False
+    # A lost mutation response does not prove failure; retrying could mutate again.
+    configuration.retries = 0
+    transport = client.ApiClient(configuration)
+    # DynamicClient's discovery calls do not accept a timeout argument. Set a
+    # transport default, while allowing explicit per-operation overrides.
+    original_call = transport.call_api
+
+    def call_api(*args: Any, **kwargs: Any) -> Any:
+        """Give discovery requests a timeout when DynamicClient passes None."""
+        if kwargs.get("_request_timeout") is None:
+            kwargs["_request_timeout"] = request_timeout
+        return original_call(*args, **kwargs)
+
+    transport.call_api = call_api
+    try:
+        return DynamicClient(transport)
+    except Exception:
+        transport.close()
+        raise
+
+
+@contextmanager
+def _using_api(
+    api: Optional[DynamicClient], request_timeout: RequestTimeout
+) -> Iterator[DynamicClient]:
+    """Reuse an injected client; open and always close a local client when omitted."""
+    owned = api is None
+    active = connect(request_timeout=request_timeout) if owned else api
+    try:
+        yield active
+    finally:
+        if owned:
+            active.client.close()
+
+
+def process(
+    template_name: str,
+    parameters: Optional[Parameters] = None,
+    *,
+    namespace: str,
+    template_namespace: Optional[str] = None,
+    api: Optional[DynamicClient] = None,
+    for_delete: bool = False,
+    request_timeout: RequestTimeout = REQUEST_TIMEOUT,
+) -> List[Manifest]:
+    """Return manifests rendered by OpenShift, without applying them.
+
+    template_name is fetched from template_namespace (defaults to namespace).
+    parameters override matching defaults; unresolved generators are rejected.
+    namespace selects the processing endpoint. api is caller-owned; if omitted,
+    a local client is opened/closed. request_timeout is seconds or (connect, read).
+    for_delete is retained for compatibility; deterministic checks always apply.
+    Raises ValueError for invalid inputs/parameters; API and transport errors
+    propagate. Returned dictionaries can contain Secret data.
+
+    Example: process("worker", {"VM_NAME": "job-001"}, namespace="workers")"""
+    _validate_inputs(template_name, parameters, namespace, template_namespace, request_timeout)
+    with _using_api(api, request_timeout) as active:
+        templates = active.resources.get(api_version=API_VERSION, kind="Template", name="templates")
+        # Read from the source namespace, but process into the target namespace.
+        # All overrides affect this copy; the stored Template stays unchanged.
+        template = deepcopy(
+            templates.get(
+                name=template_name,
+                namespace=template_namespace if template_namespace is not None else namespace,
+                _request_timeout=request_timeout,
+            ).to_dict()
+        )
+        # Source UID, namespace, and resourceVersion do not belong on a processing POST.
+        template["metadata"] = {"name": template_name}
+        template.pop("status", None)
+        definitions = {p["name"]: p for p in template.get("parameters", [])}
+        unknown = set(parameters or {}) - set(definitions)
+        if unknown:
+            raise ValueError(f"Unknown template parameters: {', '.join(sorted(unknown))}")
+        for name, value in (parameters or {}).items():
+            parameter = definitions[name]
+            parameter["value"] = str(value).lower() if isinstance(value, bool) else str(value)
+            # Even an explicit empty string is deterministic and disables generation.
+            parameter.pop("generate", None)
+            parameter.pop("from", None)
+        # Apply the same rule to every operation so replay after restart cannot
+        # silently generate different names or values. OpenShift does substitution.
+        generated = [
+            p["name"] for p in definitions.values() if p.get("generate") and not p.get("value")
+        ]
+        if generated:
+            raise ValueError(
+                "Unresolved parameter generators: "
+                + ", ".join(generated)
+                + ". Supply explicit values for deterministic replay."
+            )
+        processor = active.resources.get(
+            api_version=API_VERSION, kind="Template", name="processedtemplates"
+        )
+        objects = (
+            processor.create(body=template, namespace=namespace, _request_timeout=request_timeout)
+            .to_dict()
+            .get("objects", [])
+        )
+        if not isinstance(objects, list):
+            raise ValueError("Processed Template objects must be a list")
+        return objects
+
+
+def _targets(
+    api: DynamicClient, objects: List[Manifest], namespace: str
+) -> List[Tuple[Resource, Manifest]]:
+    """Return discovered resources paired with copied, namespace-normalized manifests.
+
+    Validate every identity and reject generated names, cross-namespace targets,
+    and cluster-scoped kinds before any target resource is read or mutated.
+    API discovery may contact the server during validation."""
+    if not isinstance(objects, list):
+        raise ValueError("resources must be a list of manifest dictionaries")
+    targets = []
+    for original in objects:
+        obj = deepcopy(original)
+        if not isinstance(obj, dict) or not isinstance(obj.get("metadata"), dict):
+            raise ValueError("Every resource must be a manifest with a metadata dictionary")
+        metadata = obj["metadata"]
+        if "generateName" in metadata:
+            raise ValueError("metadata.generateName is unsupported; require stable metadata.name")
+        for field in ("apiVersion", "kind"):
+            if not isinstance(obj.get(field), str) or not obj[field]:
+                raise ValueError(f"Every resource must have a nonempty {field}")
+        if not isinstance(metadata.get("name"), str) or not metadata["name"].strip():
+            raise ValueError("Every resource must have a nonempty metadata.name")
+        if metadata["name"] in (".", "..") or any(c in metadata["name"] for c in "/%"):
+            raise ValueError("metadata.name must be a safe API path segment")
+        if metadata.get("namespace") not in (None, "", namespace):
+            raise ValueError(f"Resource {metadata['name']} targets a different namespace")
+        resource = api.resources.get(api_version=obj["apiVersion"], kind=obj["kind"])
+        if not resource.namespaced:
+            raise ValueError(f"Cluster-scoped resource is unsupported: {obj['kind']}")
+        # An omitted/empty namespace inherits the target; an explicit other one fails.
+        metadata["namespace"] = namespace
+        targets.append((resource, obj))
+    return targets
+
+
+def _reference(obj: Manifest) -> Manifest:
+    """Return only API version, kind, name, namespace, and any UID; exclude payload data."""
+    metadata = obj["metadata"]
+    return {
+        "apiVersion": obj["apiVersion"],
+        "kind": obj["kind"],
+        "metadata": {key: metadata[key] for key in ("name", "namespace", "uid") if key in metadata},
+    }
+
+
+def _prepare_apply(obj: Manifest) -> None:
+    """Remove server-managed fields and normalize core Secret stringData in a copy.
+
+    stringData values become UTF-8/base64 data and override matching data keys.
+    Invalid Secret maps raise ValueError before any resource is applied."""
+    obj.pop("status", None)
+    # A Template may contain exported objects. Their old server-assigned fields
+    # must not be submitted as the identity/version of the object being applied.
+    fields = (
+        "uid resourceVersion managedFields creationTimestamp generation "
+        "deletionTimestamp deletionGracePeriodSeconds"
+    )
+    for key in fields.split():
+        obj["metadata"].pop(key, None)
+    # stringData does not work well with SSA; normalize it to the persisted data
+    # representation, with stringData winning collisions as in the Secret API.
+    if obj["apiVersion"] == "v1" and obj["kind"] == "Secret" and "stringData" in obj:
+        strings, data = obj.pop("stringData"), obj.setdefault("data", {})
+        if not isinstance(strings, dict) or not isinstance(data, dict):
+            raise ValueError("Secret stringData and data must be dictionaries")
+        for key, value in strings.items():
+            if not isinstance(key, str) or not isinstance(value, str):
+                raise ValueError("Secret stringData must map string keys to string values")
+            data[key] = b64encode(value.encode("utf-8")).decode("ascii")
+
+
+def create(
+    template_name: str,
+    parameters: Optional[Parameters] = None,
+    *,
+    namespace: str,
+    template_namespace: Optional[str] = None,
+    api: Optional[DynamicClient] = None,
+    field_manager: str = "mini-scheduler",
+    request_timeout: RequestTimeout = REQUEST_TIMEOUT,
+) -> List[Manifest]:
+    """Process and server-side apply a Template; return identity references in order.
+
+    References include the UID returned by the server. Retaining these references
+    is optional; template-based delete needs only the original job inputs.
+
+    template_name/parameters identify the Template and scalar overrides; namespace
+    bounds all targets; template_namespace defaults to namespace. api is caller-owned
+    (or a local client is opened/closed). request_timeout is seconds or (connect, read).
+    field_manager names the SSA owner; conflicts are never forced. All identities
+    are checked before applying. Invalid targets raise ValueError; processing errors
+    propagate. First apply failure raises OperationError with earlier successes.
+    There is no rollback or readiness wait.
+
+    Example: create("worker", {"VM_NAME": "job-001"}, namespace="workers")"""
+    _validate_inputs(template_name, parameters, namespace, template_namespace, request_timeout)
+    if not isinstance(field_manager, str) or not field_manager.strip() or len(field_manager) > 128:
+        raise ValueError("field_manager must be a nonempty string of at most 128 characters")
+    with _using_api(api, request_timeout) as active:
+        objects = process(
+            template_name,
+            parameters,
+            namespace=namespace,
+            template_namespace=template_namespace,
+            api=active,
+            request_timeout=request_timeout,
+        )
+        # Check every target and normalize every Secret before the first mutation.
+        targets = _targets(active, objects, namespace)
+        for _, obj in targets:
+            _prepare_apply(obj)
+        applied = []
+        for resource, obj in targets:
+            try:
+                result = active.server_side_apply(
+                    resource,
+                    name=obj["metadata"]["name"],
+                    body=obj,
+                    namespace=namespace,
+                    field_manager=field_manager,
+                    force_conflicts=False,
+                    _request_timeout=request_timeout,
+                ).to_dict()
+                # The apply response supplies the live UID, including when updating
+                # an existing object. No separate GET or local UID storage is needed.
+                applied.append(_reference(result))
+            except Exception as error:
+                raise OperationError("Apply", applied, [(_reference(obj), error)]) from error
+        return applied
+
+
+def delete(
+    template_name: Optional[str] = None,
+    parameters: Optional[Parameters] = None,
+    *,
+    namespace: str,
+    template_namespace: Optional[str] = None,
+    resources: Optional[List[Manifest]] = None,
+    api: Optional[DynamicClient] = None,
+    request_timeout: RequestTimeout = REQUEST_TIMEOUT,
+) -> List[Manifest]:
+    """Reprocess a Template and delete its identities in reverse order, without inventory.
+
+    Use the same template_name/parameters and compatible revision as create.
+    namespace bounds deletion; template_namespace defaults to namespace. Alternatively,
+    resources accepts references instead: omit template_name (its default is None)
+    and all other template inputs. One input mode is required; do not mix them.
+    Supplied UIDs become deletion preconditions; references without UIDs are valid.
+    Template replay deletes by name/namespace, without fetching live resource UIDs.
+    api is caller-owned (or a local client is opened/closed). request_timeout is
+    seconds or (connect, read) per request.
+    Returns successful references, including 404s. Invalid targets raise ValueError;
+    processing errors propagate. Other delete failures are collected in OperationError
+    after attempting all targets. Name-based replay has no original-UID protection.
+
+    Examples:
+        delete("worker", {"VM_NAME": "job-001"}, namespace="workers")
+        delete(namespace="workers", resources=refs)  # Optional references from create.
+    """
+    _validate_inputs(
+        template_name, parameters, namespace, template_namespace, request_timeout, resources
+    )
+    with _using_api(api, request_timeout) as active:
+        if resources is None:
+            # Reconstruct identities from the stored Template and job inputs. This
+            # works in a fresh process without a create result, inventory, or UID.
+            resources = process(
+                template_name,
+                parameters,
+                namespace=namespace,
+                template_namespace=template_namespace,
+                api=active,
+                request_timeout=request_timeout,
+            )
+        # Validate the entire set before issuing the first DELETE.
+        targets = _targets(active, resources, namespace)
+        deleted, failures = [], []
+        for resource, obj in reversed(targets):
+            ref = _reference(obj)
+            options = {
+                "apiVersion": "v1",
+                "kind": "DeleteOptions",
+                "propagationPolicy": "Background",
+            }
+            # Validation permits template_name=None only in resources mode.
+            # A caller-retained UID optionally protects against deleting a replacement
+            # with the same name (the server rejects a mismatch with 409). Template
+            # replay must not trust a UID embedded in a rendered/exported manifest.
+            # No live UID is fetched: it could belong to a replacement object.
+            if template_name is None and ref["metadata"].get("uid"):
+                options["preconditions"] = {"uid": ref["metadata"]["uid"]}
+            try:
+                resource.delete(
+                    name=ref["metadata"]["name"],
+                    namespace=namespace,
+                    body=options,
+                    _request_timeout=request_timeout,
+                )
+                # API acceptance does not mean finalizers/background deletion finished.
+                deleted.append(ref)
+            except NotFoundError:
+                # An absent target already satisfies deletion, including on replay.
+                deleted.append(ref)
+            except Exception as error:
+                # Continue cleanup, then expose every failure and earlier success.
+                failures.append((ref, error))
+        if failures:
+            raise OperationError("Delete", deleted, failures) from failures[0][1]
+        return deleted
+
+
+def get(
+    template_name: Optional[str] = None,
+    parameters: Optional[Parameters] = None,
+    *,
+    namespace: str,
+    template_namespace: Optional[str] = None,
+    resources: Optional[List[Manifest]] = None,
+    api: Optional[DynamicClient] = None,
+    request_timeout: RequestTimeout = REQUEST_TIMEOUT,
+) -> List[Manifest]:
+    """Read deployed resources and return their full live dictionaries.
+
+    Supply template_name/parameters, or resources containing identity references.
+    Omit template_name (default None) and other template inputs when using resources.
+    Reads use name/namespace and return the current object; supplied UIDs are not
+    checked, so get() cannot establish an original object's UID after replacement.
+    namespace bounds all reads; template_namespace locates the source Template.
+    api is caller-owned; without it a local client is opened and closed.
+    request_timeout is seconds or (connect, read) seconds per request.
+    Results follow rendered/reference order and include each kind's own status,
+    if present. There is no readiness interpretation or polling. Results can
+    contain Secret data. ValueError reports invalid inputs/targets; API errors
+    (including 404/403) and timeouts propagate immediately, without partial results.
+
+    Example: get("worker", {"VM_NAME": "job-001"}, namespace="workers")
+    """
+    _validate_inputs(
+        template_name, parameters, namespace, template_namespace, request_timeout, resources
+    )
+    with _using_api(api, request_timeout) as active:
+        if resources is None:
+            resources = process(
+                template_name,
+                parameters,
+                namespace=namespace,
+                template_namespace=template_namespace,
+                api=active,
+                request_timeout=request_timeout,
+            )
+        targets = _targets(active, resources, namespace)
+        return [
+            resource.get(
+                name=obj["metadata"]["name"], namespace=namespace, _request_timeout=request_timeout
+            ).to_dict()
+            for resource, obj in targets
+        ]