Troubleshooting Guide¶

This guide helps you resolve common issues with the Kubernetes integration for Home Assistant.

Authentication Issues (401 Unauthorized)¶

Problem¶

You see errors like:

Failed to stop deployment longhorn-ui
Failed to get deployments: (401)
Reason: Unauthorized

Solution¶

Step 1: Verify RBAC Setup¶

Check whether the ServiceAccount actually has the permission the failing call needs:

kubectl auth can-i list deployments \
  --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

# Everything the ServiceAccount is allowed to do
kubectl auth can-i --list \
  --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

If a verb is missing, install or upgrade the RBAC (see the next step). The full permission matrix is in the RBAC Reference Guide.

Step 2: Install or Upgrade the RBAC¶

If you prefer to set up RBAC manually:

Install the RBAC — with Helm:

helm install ha-k8s-rbac oci://ghcr.io/tibuntu/charts/homeassistant-kubernetes-rbac \
  --namespace homeassistant --create-namespace

Or with the plain manifests:

kubectl apply -f manifests/full/         # or manifests/minimal/

Extract the token:

kubectl get secret homeassistant-kubernetes-integration-token -n homeassistant -o jsonpath='{.data.token}' | base64 -d

Step 3: Verify Token Permissions¶

Test if your token has the correct permissions:

# Replace YOUR_TOKEN with the actual token
curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_CLUSTER_HOST:6443/api/v1/

# Test deployment scaling permissions
curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_CLUSTER_HOST:6443/apis/apps/v1/namespaces/default/deployments

Step 4: Update the Token in Home Assistant¶

When the cluster rejects the stored token, the integration detects it on the next poll and Home Assistant shows a "Reauthentication needed" notification for the entry. Click Reconfigure on that notification, paste the new token, and submit — the host, port, and TLS settings are kept as they are.

You can also update the token at any time without waiting for the prompt:

Go to Settings → Devices & Services
Find your Kubernetes integration and click Configure
Update the API token with the new token from Step 1 or 2
Save the configuration

Note: If Home Assistant runs inside the cluster with Use in-cluster ServiceAccount at runtime enabled, routine token rotation is handled automatically — the integration re-reads the projected token and retries before ever asking you to re-authenticate. A reauthentication prompt in that setup usually means the ServiceAccount or its ClusterRoleBinding was deleted — submitting a token there also switches the entry off in-cluster mode so the pasted token takes effect. Re-enable Use in-cluster ServiceAccount at runtime via Reconfigure once the ServiceAccount is back.

Required RBAC Permissions¶

The service account needs these permissions:

# Read permissions
- apiGroups: [""]
  resources: ["pods", "nodes", "namespaces"]
  verbs: ["get", "list", "watch"]

# Deployment permissions (including scaling)
- apiGroups: ["apps"]
  resources: ["deployments", "deployments/scale"]
  verbs: ["get", "list", "watch", "patch", "update"]

Connection Issues¶

Problem¶

Cannot connect to Kubernetes API server.

Solution¶

Verify Cluster Accessibility

kubectl cluster-info

Check Network Connectivity

# Test if the API server is reachable
curl -k https://YOUR_CLUSTER_HOST:6443/api/v1/

Verify SSL Certificate
If using self-signed certificates, set verify_ssl: false in the configuration
For custom CA certificates, provide the certificate path in the configuration

Deployment Scaling Issues¶

Problem¶

Deployment scaling operations fail.

Solution¶

Check Deployment Exists

kubectl get deployments -n NAMESPACE

Verify Namespace
Ensure the deployment is in the correct namespace
Check if you're monitoring all namespaces or a specific one
Check Resource Quotas

kubectl describe resourcequota -n NAMESPACE

Common Configuration Issues¶

Problem¶

Integration shows incorrect data or no data.

Solution¶

Check Namespace Configuration
If monitor_all_namespaces: false, ensure the selected namespaces exist in your cluster
If monitor_all_namespaces: true, ensure you have cluster-wide permissions
Verify Host Configuration
Remove protocol prefixes (http://, https://) from the host
Use only the hostname or IP address
Check Port Configuration
Default Kubernetes API port is 6443
For k3s, it might be 6443 or 6443
Verify with kubectl config view

Debugging¶

Enable Debug Logging¶

Add this to your configuration.yaml:

logger:
  default: info
  logs:
    custom_components.kubernetes: debug

Check Home Assistant Logs¶

Look for detailed error messages in the Home Assistant logs:

# If running in Docker
docker logs homeassistant

# If running in Kubernetes
kubectl logs -n homeassistant deployment/homeassistant

Test API Endpoints Manually¶

Use curl to test API endpoints directly:

# Test basic connectivity
curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_CLUSTER_HOST:6443/api/v1/

# Test deployments endpoint
curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_CLUSTER_HOST:6443/apis/apps/v1/namespaces/default/deployments

# Test scaling endpoint
curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/strategic-merge-patch+json" \
  -d '{"spec":{"replicas":0}}' \
  https://YOUR_CLUSTER_HOST:6443/apis/apps/v1/namespaces/default/deployments/DEPLOYMENT_NAME/scale

Downloading Diagnostics for Bug Reports¶

Home Assistant can export a redacted snapshot of the integration's configuration and runtime state. Attaching this to a GitHub issue is the fastest way to get a useful response.

Go to Settings → Devices & Services.
Find the Kubernetes integration and click the ⋮ menu next to your cluster.
Choose Download diagnostics.
Attach the resulting JSON file to your GitHub issue.

The export includes the cluster host, namespaces, watch/panel options, coordinator status, and resource counts. The API token and CA certificate are automatically redacted before download.

Getting Help¶

If you're still experiencing issues:

Check the logs with debug logging enabled
Verify your Kubernetes cluster is working correctly
Test the API endpoints manually using curl
Create an issue on the GitHub repository with:
Home Assistant version
Kubernetes version
Error logs
Diagnostics download (see section above)
Configuration (without sensitive data)

Security Best Practices¶

Use Service Accounts: Always use service accounts instead of user tokens
Principle of Least Privilege: Only grant necessary permissions
Regular Token Rotation: Rotate tokens periodically
Network Security: Use network policies to restrict access
Audit Logging: Enable audit logging to monitor API access