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.

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:

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)

Switch Features¶

• Real-time State: Switches automatically reflect the actual Kubernetes state through 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)

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)
│   ├── Individual Node sensors (one per node)
│   └── Node condition binary sensors (4 per node: Memory/Disk/PID Pressure, Network Unavailable)
│
└── 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)
• 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)
• Cluster-wide metrics (pods, nodes, deployments, statefulsets, daemonsets, cronjobs, jobs 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.