Cluster Health

The health of the platform’s Kubernetes cluster, as its cloud provider reports it.

Kubernetes itself reports the health of pods and nodes. The cloud provider that runs the cluster reports what Kubernetes cannot see: whether the control plane is healthy, whether each node group can launch its instances, whether each add-on (e.g. coredns or vpc-cni) is healthy and has a newer version, and the provider’s recommendations, e.g. EKS’s insights about the cluster’s readiness for the next Kubernetes version.

get_kubernetes_cluster_health() returns a ClusterHealth, built from these models, whichever cloud runs the cluster. For AWS, the EKS helper, get_cluster_health(), fills it. Each part is read on its own: a part that cannot be read, e.g. because the platform’s cloud credentials may not list insights, is named in ClusterHealth.errors, and the other parts are still returned.

The Smarter Operations MCP server’s eks_status tool (EksStatusTool) reports it.

class smarter.apps.infrastructure.cluster_health.AddonHealth(**data)[source]

Bases: BaseModel

One add-on of the cluster: a component that the cloud provider installs and updates, e.g. coredns.

It records the add-on’s version, and the newest version that the provider offers for the cluster’s Kubernetes version, so that an outdated add-on can be reported.

issues: tuple[HealthIssue, ...]: The add-on’s health issues, or none.

latest_version: str | None: The newest version for the cluster’s Kubernetes version, or None if it could not be read.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str: The add-on’s name, e.g. coredns, kube-proxy or vpc-cni.

status: str: The provider’s status, e.g. ACTIVE, DEGRADED or UPDATING.

property update_available: bool

Whether a newer version of the add-on is available for the cluster’s Kubernetes version.

Returns:: True if latest_version is known and newer than version, compared by their numbers (see version_key()).

version: str: The add-on’s installed version, e.g. v1.11.4-eksbuild.2.

class smarter.apps.infrastructure.cluster_health.ClusterHealth(**data)[source]

Bases: BaseModel

The health of the platform’s Kubernetes cluster: its control plane, node groups, add-ons and insights.

Every list is empty when its part has nothing in it, or could not be read. errors tells the two apart.

addons: list[AddonHealth]: The cluster’s add-ons.

errors: list[str]: The parts that could not be read, and why, e.g. insights: AccessDeniedException.

insights: list[ClusterInsight]: The provider’s insights about the cluster.

issues: tuple[HealthIssue, ...]: The control plane’s health issues, or none.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str: The cluster’s name.

nodegroups: list[NodeGroupHealth]: The cluster’s node groups.

platform_version: str: The provider’s version of the control plane, e.g. eks.9.

status: str: The control plane’s status, e.g. ACTIVE, UPDATING or FAILED.

version: str: The cluster’s Kubernetes version, e.g. 1.33.

class smarter.apps.infrastructure.cluster_health.ClusterInsight(**data)[source]

Bases: BaseModel

One recommendation of the cloud provider about the cluster, e.g. an EKS insight.

EKS checks the cluster regularly, e.g. for apis that the next Kubernetes version removes, and reports each check as passing, or as a warning or error, with a reason.

category: str: The kind of insight, e.g. UPGRADE_READINESS or MISCONFIGURATION.

kubernetes_version: str: The Kubernetes version that the insight is about, e.g. the next one, or empty if it is about none.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str: The insight’s name, e.g. “Deprecated APIs removed in Kubernetes v1.34”.

reason: str: Why the check has this result, in the provider’s words.

status: str

PASSING, WARNING, ERROR or UNKNOWN.

Type:: The result of the check

class smarter.apps.infrastructure.cluster_health.HealthIssue(**data)[source]

Bases: BaseModel

A health issue that the cloud provider reports for the cluster, a node group or an add-on.

e.g. EKS reports Ec2LaunchTemplateNotFound for a node group whose launch template was deleted, or InsufficientNumberOfReplicas for an add-on whose pods are not running.

code: str: The provider’s code for the issue, e.g. AsgInstanceLaunchFailures.

message: str: The provider’s explanation of the issue.

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

resources: tuple[str, ...]: The provider’s ids of the resources that the issue affects, e.g. EC2 instance ids.

class smarter.apps.infrastructure.cluster_health.NodeGroupHealth(**data)[source]

Bases: BaseModel

One node group of the cluster: a set of identical nodes that the cloud provider launches and replaces.

Its size is kept between its minimum and maximum by the cluster autoscaler, and its status says whether the provider can manage it, e.g. DEGRADED when it cannot launch instances.

capacity_type: str

ON_DEMAND, or SPOT, which AWS can take back at short notice.

Type:: How the instances are bought

desired_size: int | None: The number of nodes that the group runs now, as the autoscaler set it.

instance_types: tuple[str, ...]: The instance types that the group may launch, e.g. ("t3.xlarge",).

issues: tuple[HealthIssue, ...]: The node group’s health issues, or none.

max_size: int | None

The most nodes that the group may run.

A group at its maximum cannot add room for more pods.

min_size: int | None: The fewest nodes that the group may run.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str: The node group’s name.

release_version: str: The version of the nodes’ image, e.g. an EKS optimized AMI release.

status: str: The provider’s status, e.g. ACTIVE, UPDATING or DEGRADED.

smarter.apps.infrastructure.cluster_health.version_key(version)[source]

Turn a version into a tuple of its numbers, so that versions compare as versions, not as text.

As text, v1.9.0 sorts after v1.19.0. As tuples, (1, 9, 0) sorts before (1, 19, 0).

Parameters:: version (str) – The version, e.g. v1.19.0-eksbuild.2.
Return type:: tuple[int, ...]
Returns:: Its numbers, in order, e.g. (1, 19, 0, 2), or an empty tuple if it has none.