Configuration Guide¶

This guide covers all configuration options for the Kubernetes Home Assistant Integration.

Required Settings¶

Optional Settings¶

Configuration via UI¶

The integration uses a two-step configuration process:

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for "Kubernetes"
4. Step 1 - Connection Details: Fill in the required connection information:
5. Cluster Name (used as the integration name)
6. Kubernetes API Host
7. API Token
8. Optional: Port, CA Certificate, Verify SSL, and other settings
9. Monitor All Namespaces (defaults to true)
10. Step 2 - Namespace Selection (only if "Monitor All Namespaces" is disabled):
11. The integration will automatically fetch available namespaces from your cluster
12. Select one or more namespaces from the dropdown list
13. You can select multiple namespaces by clicking on them

Reconfiguring the Integration¶

To change connection details or settings for an existing integration entry:

1. Go to Settings → Devices & Services
2. Find the Kubernetes integration card
3. Click the three-dot menu (...) and select Reconfigure
4. Update the desired settings (host, port, API token, SSL, namespaces, polling intervals, grouping mode)
5. If "Monitor All Namespaces" is disabled, you will be prompted to select namespaces in a second step

Note: The cluster name cannot be changed during reconfiguration as it serves as the unique identifier for the integration entry. To change the cluster name, remove and re-add the integration.

Re-authentication¶

If the Kubernetes API starts rejecting the stored API token (HTTP 401 — the token expired, was revoked, or its ServiceAccount was deleted), the integration stops polling and Home Assistant raises a "Reauthentication needed" notification for that entry. Opening it shows a form that asks for a new API token only; the host, port, CA certificate, SSL, and namespace settings stay as configured. Once a valid token is submitted, the entry is updated and reloaded automatically.

Entries using Use in-cluster ServiceAccount at runtime re-read the projected token file and retry before reporting an authentication failure, so ordinary token rotation never triggers this prompt. If such an entry does reach re-authentication, the projected token is being rejected persistently — submitting a token therefore also turns Use in-cluster ServiceAccount at runtime off for that entry, so the token you entered is the one actually used. Re-enable the checkbox via Reconfigure once the ServiceAccount is healthy again. See Authentication Issues for how to obtain a fresh token.

Dashboard Panel¶

Once the integration is set up, a Kubernetes entry appears in the Home Assistant sidebar. The panel provides a built-in cluster dashboard with six tabs:

• Overview — Cluster health badge, resource count cards, namespace breakdown, Watch API status, and alerts (nodes with pressure, degraded workloads, failed pods). Updates live whenever cluster data changes — immediately via the Watch API (enabled by default), otherwise on each coordinator poll cycle — with a 60-second fallback refresh.
• Nodes — Sortable table of all cluster nodes with status, roles, OS/kernel info, real-time CPU/memory usage (requires metrics-server), resource capacity, and conditions. Filterable by name, status, and role.
• Workloads — Management view for Deployments, StatefulSets, DaemonSets, CronJobs, and Jobs. Start/stop/scale controls for deployments and statefulsets, suspend/resume for cronjobs. Filterable by type, namespace, and status.
• Pods — Sortable table of all pods with phase, containers, restarts, node, IP, and age. Filterable by name, namespace, phase, and node.
• Network — Table of all Ingresses with class, clickable URLs (derived from TLS coverage), backing service, TLS status, and age. Filterable by name, namespace, and host. Auto-refreshes every 30 seconds.
• Settings — Read-only view of current integration configuration (connection, namespaces, timing, features). Links to the HA integration page for editing settings.

The panel is registered automatically by default. To disable it, go to Settings > Devices & Services > Kubernetes > Configure and set Enable Panel to off. The panel is shown if any configured cluster entry has it enabled.

Advanced Configuration¶

Namespace Monitoring¶

• All Namespaces (default): Set "Monitor All Namespaces" to true to monitor all namespaces in your cluster. Requires cluster-wide permissions.
• Selected Namespaces: Set "Monitor All Namespaces" to false to select specific namespaces. You'll be prompted in a second step to choose which namespaces to monitor from a dropdown list populated from your cluster.

SSL Configuration¶

For self-signed certificates or custom CA:

• Verify SSL defaults to false to support self-signed certificates out of the box
• Set "Verify SSL" to true for production environments with proper certificates
• Provide the CA certificate path for custom Certificate Authorities

Performance Tuning¶

• Switch Update Interval: Lower values provide more responsive switches but increase API load
• Scale Verification Timeout: Increase for slow clusters or large deployments
• Scale Cooldown: Prevents rapid successive scaling operations

Options (post-setup)¶

After the integration is set up, you can configure additional options by clicking Configure on the integration card in Settings → Devices & Services.

Watch API¶

When enabled (the default), the integration establishes long-lived HTTP streams to the Kubernetes API server and receives ADDED, MODIFIED, and DELETED events as they happen. Pod and resource state changes typically appear in Home Assistant within seconds. Polling continues every 5 minutes as a fallback. Disable the option to use interval polling only (the Switch Update Interval, 60 seconds by default).

RBAC: The watch feature requires the service account to have watch permission on all monitored resources — granted by the full permission set, but not by minimal. If the permission is missing, the watch connection cannot be established: the integration raises a repair issue and automatically falls back to regular interval polling, so data stays current. See the RBAC guide for details.

Changing this option reloads the integration automatically.

Cluster Events¶

When Enable Cluster Events is on, the integration creates one event entity per cluster named Cluster events. It tails the Kubernetes Events API using the same hardened watch infrastructure as the Watch API feature and dispatches matching events to Home Assistant.

The Kubernetes event reason becomes the HA event_type. A curated set of reasons (OOMKilling, FailedScheduling, BackOff, Evicted, Unhealthy, ImagePullBackOff, and others) are surfaced as distinct types; any unrecognised reason maps to other. Each event carries attributes for the involved object kind, name, namespace, message, count, and timestamp.

Note: The cluster event watch loop is independent of the Watch API toggle — enabling one does not enable the other.

RBAC: Reading Kubernetes events requires get, list, and watch verbs on the core v1 events resource. The full permission set (mode: full / manifests/full/) already grants these. The minimal set does not include events — with the Helm chart, add them via rbac.extraRules:

rbac:
  extraRules:
    - apiGroups: [""]
      resources: ["events"]
      verbs: ["get", "list", "watch"]

With the plain manifests, add the same rule to manifests/minimal/clusterrole.yaml by hand. See the RBAC guide for details.

Changing these options reloads the integration automatically.

Data Collection Opt-Out¶

Large clusters can produce hundreds of entities and constant recorder writes. This option lets you opt out of categories you don't need, reducing entity count, database growth, and Kubernetes API load.

The categories come in two tiers:

Notes:

• Fully-skipped categories (Pods, DaemonSets, Jobs, Ingresses) also stop their watch streams when the Watch API is enabled.
• Existing entities of a disabled category are removed from Home Assistant automatically on the next update cycle.
• If a fully-skipped category is disabled while Aggregate count sensors stay enabled, its count sensor keeps working via a lightweight count API call.
• The delete_job service still works with Jobs disabled, but can no longer resolve a Job's namespace automatically — it falls back to the configured default namespace, so pass the namespace explicitly.

Changing this option reloads the integration automatically.