Kubernetes Service Reference

class smarter.apps.infrastructure.services.kubernetes.KubernetesService(provider_name, *args, **kwargs)

Bases: InfrastructureService

The platform’s Kubernetes cluster.

Implementations provide the primitives: apply_manifest(), get_resource(), list_resources(), delete_resource(), delete_resources() and get_pod_logs(), and optionally find_resources(), for the inventory. The ingress operations that LLMClient deployments use are built on them.

abstractmethod apply_manifest(manifest)

Create or update the resources of a manifest.

Raises:

KubernetesServiceError – If the cluster rejects them.

Return type:

None

certificate_wait_seconds: float = 60

Seconds between the checks of a cert-manager certificate, in verify_ingress_resources().

delete_certificate(name, namespace)

Delete a cert-manager Certificate.

Return type:

bool

delete_ingress(name, namespace)

Delete an Ingress.

Return type:

bool

delete_ingress_resources(hostname, namespace)

Delete a host’s Ingress, its cert-manager Certificate, and its TLS Secret.

Return type:

tuple[bool, bool, bool]

Returns:

Whether the Ingress, the Certificate, and the Secret were deleted.

abstractmethod delete_resource(kind, name, namespace)

Delete a resource by name.

A resource that does not exist counts as deleted.

Return type:

bool

abstractmethod delete_resources(kinds, namespace, selector)

Delete the resources of several kinds that match a label selector.

Idempotent. A selector is required, so that a namespace is never emptied by mistake.

Return type:

bool

delete_secret(name, namespace)

Delete a Secret.

Return type:

bool

error_class

alias of KubernetesServiceError

find_resources(kind, namespace=None)

Return every resource of a kind, for the inventory.

Unlike list_resources(), it tells a kind that has no resources from one that could not be listed, so that the inventory never mistakes an unavailable cluster for an empty one. This implementation cannot list, and returns None.

Parameters:

• kind (str) – The kind, e.g. node.

• namespace (str | None) – The namespace of a namespaced kind, or None for a cluster-scoped kind, e.g. a node.

Return type:

list[dict[str, Any]] | None

Returns:

The resources, or None if they could not be listed, e.g. because the cluster is unavailable, or the kind’s CustomResourceDefinition is not installed.

abstractmethod get_pod_logs(namespace, selector, container=None, tail=200)

Return the most recent log lines of the pods that match a label selector.

Return type:

str | None

abstractmethod get_resource(kind, name, namespace)

Return a resource, or None if it does not exist or the cluster is unavailable.

Return type:

dict[str, Any] | None

get_resources(resources, namespace)

Return several resources at once.

Implementations may override it to fetch them in one request. This one gets each in turn.

Parameters:

• resources (list[tuple[str, str]]) – The (kind, name) of each resource, with a lowercase kind, e.g. ("ingress", "app").

• namespace (str) – The namespace.

Return type:

dict[tuple[str, str], dict[str, Any]]

Returns:

The resources that exist, keyed by their (kind, name).

abstractmethod list_resources(kind, namespace, selector=None)

Return the resources of a kind, optionally those that match a label selector.

Return type:

list[dict[str, Any]]

service_name: str = 'kubernetes'

The name of the service in signals and logs, see InfrastructureServiceNames.

verify_certificate(name, namespace)

Whether a cert-manager Certificate exists, and is Ready, i.e. issued.

Parameters:

• name (str) – The Certificate’s name.

• namespace (str) – The Certificate’s namespace.

Return type:

bool

verify_ingress(name, namespace)

Whether an Ingress exists.

Return type:

bool

verify_ingress_resources(hostname, namespace, max_attempts=30)

Verify that a host’s Ingress, its cert-manager Certificate, and its TLS Secret exist.

The Ingress is named after the host, and the Certificate and Secret <host>-tls.

Parameters:

• hostname (str) – The host, e.g. example.3141-5926-5359.api.example.com.

• namespace (str) – The namespace.

• max_attempts (int) – How many times to check the Certificate, a minute apart. A Celery task passes 1, and checks again later, so that it does not block its worker.

Return type:

tuple[bool, bool, bool]

Returns:

Whether the Ingress, the Certificate, and the Secret are verified.

verify_secret(name, namespace)

Whether a Secret exists.

Return type:

bool

class smarter.apps.infrastructure.services.kubernetes.KubectlKubernetesService(provider=None, allow_in_tests=False, **kwargs)

Bases: KubernetesService

The platform’s Kubernetes cluster, through kubectl.

The cluster is ready once kubectl is configured, with the provider’s update_kubeconfig(), and the environment’s namespace, smarter_settings.environment_namespace, exists.

Parameters:

• provider (CloudProvider | None) – The cloud provider that writes the kubeconfig. None for a cluster whose kubeconfig is already in place.

• allow_in_tests (bool) – Allow kubectl in the unit tests, e.g. when subprocess is mocked.

__init__(provider=None, allow_in_tests=False, **kwargs)

apply_manifest(manifest)

Create or update the resources of a manifest, with kubectl apply.

Resources that provision billable cloud resources, see billable_resources(), are announced with the billable resource signals. Nothing is applied if the cluster is not ready.

Parameters:

manifest (str) – The manifest, which may have several YAML documents.

Raises:

KubernetesServiceError – If the cluster rejects it.

Return type:

None

property configured: bool

Whether kubectl is configured for the cluster.

delete_resource(kind, name, namespace)

Delete a resource by name.

A resource that does not exist counts as deleted.

Return type:

bool

delete_resources(kinds, namespace, selector)

Delete the resources of several kinds that match a label selector.

Idempotent. A selector is required, so that a namespace is never emptied by mistake.

Return type:

bool

find_resources(kind, namespace=None)

Return every resource of a kind, for the inventory.

Unlike list_resources(), it tells a kind that has no resources from one that could not be listed, so that the inventory never mistakes an unavailable cluster for an empty one. This implementation cannot list, and returns None.

Parameters:

• kind (str) – The kind, e.g. node.

• namespace (str | None) – The namespace of a namespaced kind, or None for a cluster-scoped kind, e.g. a node.

Return type:

list[dict[str, Any]] | None

Returns:

The resources, or None if they could not be listed, e.g. because the cluster is unavailable, or the kind’s CustomResourceDefinition is not installed.

get_pod_logs(namespace, selector, container=None, tail=200)

Return the most recent log lines of the pods that match a label selector.

Return type:

str | None

get_resource(kind, name, namespace)

Return a resource, or None if it does not exist or the cluster is unavailable.

Return type:

dict[str, Any] | None

get_resources(resources, namespace)

Return several resources with one kubectl get.

Each kubectl call fetches a cluster token, e.g. with aws eks get-token, which takes seconds, so one call rather than several frees a Celery worker sooner. If the call fails, e.g. because a kind’s CustomResourceDefinition is not installed, each resource is fetched in turn.

Return type:

dict[tuple[str, str], dict[str, Any]]

property kubeconfig: dict[str, Any]

The platform’s kubeconfig file.

property kubeconfig_path: str

The path of the platform’s kubeconfig file.

list_resources(kind, namespace, selector=None)

Return the resources of a kind, optionally those that match a label selector.

Return type:

list[dict[str, Any]]

property namespace_verified: bool

Whether the environment’s namespace exists.

property ready: bool

Whether the service is authenticated and connected, i.e. it can be used.

verify_namespace(namespace)

Whether a namespace exists.

Return type:

bool