Entities Documentation¶

This document describes all sensors, binary sensors, and switches provided by the Kubernetes integration.

Sensors¶

The integration provides the following sensors to monitor your Kubernetes cluster:

Individual Node Sensors¶

The integration creates a separate sensor for each Kubernetes node in the cluster:

Individual DaemonSet Sensors¶

The integration creates a separate sensor for each Kubernetes DaemonSet in the monitored namespace(s):

DaemonSet Sensor Attributes¶

Each DaemonSet sensor provides scheduling and readiness information:

Status values: - Ready — all desired pods are ready (ready == desired) - Degraded — some but not all pods are ready (0 < ready < desired) - Not Ready — no pods are ready (ready == 0) - Unknown — data is unavailable or no nodes are scheduled

Workload Status Sensors¶

The integration creates a readiness status sensor for each deployment and statefulset:

Status values: - Ready — all desired replicas are ready (ready_replicas == replicas > 0) - Degraded — some but not all replicas are ready (0 < ready_replicas < replicas) - Not Ready — no replicas are ready (ready_replicas == 0 and replicas > 0) - Scaled Down — workload is intentionally scaled to zero (replicas == 0) - Unknown — data is unavailable

Each sensor exposes the following attributes: namespace, replicas, ready_replicas, available_replicas.

Workload Metric Sensors¶

The integration creates CPU and memory usage sensors for each deployment and statefulset. These sensors read live data from the metrics-server and require it to be installed in your cluster.

These sensors expose numeric values with SensorStateClass.MEASUREMENT, making them suitable for history tracking and use in automations:

# Scale up a deployment when CPU usage exceeds 800 millicores
trigger:
  - platform: numeric_state
    entity_id: sensor.my_app_cpu_usage
    above: 800
action:
  - service: kubernetes.scale_workload
    data:
      workload_name: my-app
      namespace: default
      replicas: 3

Note: If metrics-server is not installed, these sensors will report 0.

Tip: These sensors change on nearly every update cycle and are the biggest contributors to recorder/database growth. If you don't need them, disable the CPU/memory metrics category via Configure → Disable data collection for — see the data collection opt-out. The same option can disable other entity categories (per-pod sensors, count sensors, …) entirely.

Individual Pod Sensors¶

The integration creates a separate sensor for each Kubernetes pod in the monitored namespace(s):

Node Sensor Attributes¶

Each node sensor provides comprehensive information about the node:

Pod Sensor Attributes¶

Each pod sensor provides comprehensive information about the pod:

Note on problem/problem_reason: These derived attributes are designed for automations and alerts. A pod that OOMKilled but has since restarted successfully will have last_terminated_reason: OOMKilled yet problem: false — the flag only fires when the pod is currently broken, not for historical events.

Note on container selection: These attributes reflect the pod's application containers (containerStatuses); init-container failures are not currently inspected.

Individual Job Sensors¶

The integration creates a separate sensor for each Kubernetes Job in the monitored namespace(s):

Status values: - Complete — all completions have succeeded (succeeded >= completions) - Running — the job has active pods (active > 0) - Failed — the job has failed pods and no active ones - Unknown — data is unavailable

Job Sensor Attributes¶

Each Job sensor provides execution details:

Sensor Attributes¶

Each sensor includes additional attributes with detailed information:

• Last Updated: Timestamp of the last successful update
• Namespace: The namespace being monitored
• Cluster Name: Name of the Kubernetes cluster
• API Endpoint: Kubernetes API server endpoint

Binary Sensors¶

Node Condition Binary Sensors¶

The integration creates binary sensors for each node condition on every node in the cluster:

• States: on means the condition is active (problem detected), off means normal operation
• Device assignment: Assigned to the cluster device alongside individual node sensors

Binary Sensor Attributes¶

• Last Check: Timestamp of the last health check
• Error Message: Details about connection issues (when unhealthy)
• Response Time: API response time in milliseconds

Switches¶

The integration automatically creates switches for controlling Kubernetes workloads:

Deployment Switches¶

• Entity ID Format: switch.kubernetes_deployment_[deployment_name]
• Function: Control individual deployments (scale to 0/1 replicas)
• States:
• on: Deployment is running (replicas > 0)
• off: Deployment is stopped (replicas = 0)

StatefulSet Switches¶

• Entity ID Format: switch.kubernetes_statefulset_[statefulset_name]
• Function: Control individual statefulsets (scale to 0/1 replicas)
• States:
• on: StatefulSet is running (replicas > 0)
• off: StatefulSet is stopped (replicas = 0)

Node Schedulable Switches¶

• Entity ID Format: switch.[cluster_name]_[node_name]_schedulable
• Function: Cordon / uncordon individual nodes (patches spec.unschedulable)
• States:
• on: Node is schedulable (uncordoned)
• off: Node is cordoned (unschedulable — running pods keep running, no new pods are scheduled)
• Attributes: node_name, status, schedulable, cordoned, last_cordon_time, last_uncordon_time
• Requires: the patch verb on nodes (included in manifests/full/)

Switch Features¶

• Real-time State: Switches automatically reflect the actual Kubernetes state through the Watch API (default) or interval polling
• Error Recovery: If scaling operations fail, switches automatically recover the correct state
• State Verification: Verifies that scaling operations actually took effect
• Configurable Polling: Adjust update intervals to balance responsiveness and API load
• Failure Indication: Shows when the last scaling attempt failed via entity attributes

Switch Attributes¶

Each switch includes detailed attributes:

• Current Replicas: Current number of replicas
• Desired Replicas: Target number of replicas
• Ready Replicas: Number of ready replicas
• Last Scaled: Timestamp of the last scaling operation
• Scale Status: Success/failure status of the last scaling operation
• Namespace: Kubernetes namespace
• Resource Type: deployment or statefulset
• CPU Usage: CPU usage in millicores (for Deployments and StatefulSets)
• Memory Usage: Memory usage in MiB (for Deployments and StatefulSets)

Cluster Events¶

The integration provides an opt-in event entity per cluster that fires Home Assistant events whenever the Kubernetes cluster emits an event (e.g. a pod is OOM-killed, scheduling fails, a container enters CrashLoopBackOff).

Entity¶

The entity is only created when Enable Cluster Events is turned on under Settings → Devices & Services → Kubernetes → Configure. It is disabled by default.

Event types¶

Each fired Home Assistant event has an event_type derived from the Kubernetes event reason. A curated set of reasons are surfaced as distinct types; any unrecognised reason maps to other:

Event attributes¶

Each fired event carries the following attributes:

Filtering¶

By default only Warning-type Kubernetes events are dispatched. To also receive Normal-type events, set Event Types to all in Configure → Event Types.

Note: The watch loop anchors to the current resource version on startup so that existing events in the cluster are not replayed. Only events that occur after the integration starts are fired.

Note: Recurring conditions fire repeatedly — Kubernetes increments an existing event's count, so e.g. a CrashLoopBackOff pod emits an event on each retry.

Example automation¶

automation:
  - alias: Notify on pod OOMKill
    trigger:
      - platform: state
        entity_id: event.my_cluster_cluster_events
    condition:
      - condition: template
        value_template: "{{ trigger.to_state.attributes.event_type == 'OOMKilling' }}"
    action:
      - service: notify.notify
        data:
          message: >-
            OOMKilled: {{ trigger.to_state.attributes.involved_name }}
            in {{ trigger.to_state.attributes.namespace }}

Device Organization¶

The integration organizes entities using Home Assistant's device system, creating a hierarchical structure that makes it easier to manage large clusters:

Device Hierarchy¶

Cluster Device (e.g., "production-cluster")
├── Cluster-level entities:
│   ├── Cluster Health (binary_sensor)
│   ├── Nodes Count (sensor)
│   ├── Pods Count (sensor)
│   ├── Deployments Count (sensor)
│   ├── StatefulSets Count (sensor)
│   ├── DaemonSets Count (sensor)
│   ├── CronJobs Count (sensor)
│   ├── Jobs Count (sensor)
│   ├── Ingresses Count (sensor)
│   ├── Cluster events (event — opt-in, only when enable_events is on)
│   ├── Individual Node sensors (one per node)
│   ├── Node condition binary sensors (4 per node: Memory/Disk/PID Pressure, Network Unavailable)
│   └── Node schedulable switches (one per node: cordon / uncordon)
│
└── Namespace Devices (e.g., "production-cluster: default")
    ├── Pod sensors (all pods in this namespace)
    ├── Deployment switches (all deployments in this namespace)
    ├── Deployment status sensors (one per deployment)
    ├── Deployment CPU/memory sensors (one pair per deployment)
    ├── StatefulSet switches (all statefulsets in this namespace)
    ├── StatefulSet status sensors (one per statefulset)
    ├── StatefulSet CPU/memory sensors (one pair per statefulset)
    ├── DaemonSet sensors (all daemonsets in this namespace)
    ├── CronJob switches (all cronjobs in this namespace)
    └── Job sensors (all jobs in this namespace)

Benefits of Device Organization¶

• Better Organization: Entities are logically grouped by cluster and namespace
• Easier Filtering: Filter entities by device in the Home Assistant UI
• Clearer Context: Entity names clearly indicate which cluster and namespace they belong to
• Scalability: Better handles large clusters with many resources
• Kubernetes Alignment: Follows Kubernetes namespace organization pattern

Device Management¶

• Automatic Device Creation: Devices are automatically created when entities are first discovered
• Automatic Device Cleanup: Namespace devices are automatically removed when namespaces are deleted from the cluster
• Dynamic Updates: New namespace devices are created when new namespaces are discovered

Entity Naming¶

With device-based grouping, entities are automatically named using the following patterns:

• Cluster-level Sensors: sensor.[cluster_name]_[metric_type] (e.g., sensor.production_cluster_nodes_count)
• Cluster-level Binary Sensors: binary_sensor.[cluster_name]_cluster_health (e.g., binary_sensor.production_cluster_cluster_health)
• Node Sensors: sensor.[cluster_name]_[node_name] (e.g., sensor.production_cluster_worker_node_1)
• Node Schedulable Switches: switch.[cluster_name]_[node_name]_schedulable (e.g., switch.production_cluster_worker_node_1_schedulable)
• Namespace-level Pod Sensors: sensor.[cluster_name]_[namespace]_[pod_name] (e.g., sensor.production_cluster_default_my_app_pod)
• Namespace-level Switches: switch.[cluster_name]_[namespace]_[resource_name]_[resource_type] (e.g., switch.production_cluster_default_my_deployment_deployment)

The device hierarchy ensures that entity names include cluster and namespace context, making it clear what each entity represents.

Dynamic Entity Discovery¶

The integration automatically discovers and creates entities for:

• All deployments in monitored namespaces (switch + status sensor + CPU/memory sensors)
• All statefulsets in monitored namespaces (switch + status sensor + CPU/memory sensors)
• All daemonsets in monitored namespaces (status sensor)
• All cronjobs in monitored namespaces (switch)
• All jobs in monitored namespaces (status sensor)
• Individual Kubernetes pods in monitored namespaces
• Individual Kubernetes nodes in the cluster
• Node condition binary sensors (4 per node: Memory Pressure, Disk Pressure, PID Pressure, Network Unavailable)
• Node schedulable switches (one per node, for cordon / uncordon)
• Cluster-wide metrics (pods, nodes, deployments, statefulsets, daemonsets, cronjobs, jobs, ingresses count)
• Overall cluster health

Entities are automatically added when new resources are created and removed when resources are deleted from the cluster.

Node Entity Management¶

• Automatic Creation: Node sensors are automatically created for each node discovered during integration setup
• Dynamic Updates: Node information is refreshed during regular coordinator updates
• Automatic Cleanup: Node sensors are automatically removed when nodes are deleted from the cluster
• Entity Naming: Node entities use the format sensor.kubernetes_node_[node_name]

Pod Entity Management¶

• Automatic Creation: Pod sensors are automatically created for each pod discovered during integration setup
• Dynamic Updates: Pod information is refreshed during regular coordinator updates
• Automatic Cleanup: Pod sensors are automatically removed when pods are deleted from the cluster
• Entity Naming: Pod entities use the format sensor.kubernetes_[pod_name]
• Namespace Support: Pods are tracked by both namespace and name for proper identification
• Phase Tracking: Pod sensors show the current phase (Running, Pending, Failed, Succeeded, etc.)
• Container Status: Detailed information about container readiness and restart counts
• Owner Information: Shows which workload (Deployment, StatefulSet, etc.) owns the pod

Using Pod Entities with Auto-Entities¶

The pod entities are perfect for use with the auto-entities card to create dynamic dashboards. Here's an example configuration to show pods that are not in a Running or Completed phase:

type: custom:auto-entities
card:
  type: entities
  title: "Pods with Issues"
filter:
  include:
    - entity_id: sensor.kubernetes_*
      state:
        - "Pending"
        - "Failed"
        - "Unknown"
  exclude:
    - state: "Running"
    - state: "Succeeded"

This configuration will automatically populate a card with all pod entities that are in a problematic state, making it easy to monitor and troubleshoot your Kubernetes cluster.