Service Account Setup Guide¶

This guide walks you through setting up the required Kubernetes service account and RBAC permissions for the Home Assistant Kubernetes Integration.

Quick Setup¶

For a quick setup using the provided manifests:

1. Apply Required Manifests¶

kubectl apply -f manifests/serviceaccount.yaml
kubectl apply -f manifests/clusterrole.yaml
kubectl apply -f manifests/clusterrolebinding.yaml
kubectl apply -f manifests/serviceaccount-token-secret.yaml

2. Extract the Token¶

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

Copy this token for use in the Home Assistant configuration.

Step-by-Step Setup¶

If you prefer to understand each step or need to customize the setup:

1. Create Service Account¶

kubectl apply -f manifests/serviceaccount.yaml

This creates a service account named homeassistant-kubernetes-integration in the homeassistant namespace.

2. Create Cluster Role¶

kubectl apply -f manifests/clusterrole.yaml

This defines the RBAC permissions required for monitoring and controlling Kubernetes resources.

3. Create Cluster Role Binding¶

kubectl apply -f manifests/clusterrolebinding.yaml

This binds the cluster role to the service account, granting the necessary permissions.

4. Create Token Secret¶

kubectl apply -f manifests/serviceaccount-token-secret.yaml

This creates a secret containing the service account token for authentication.

5. Extract the Token¶

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

RBAC Permissions¶

The integration requires comprehensive permissions for monitoring and controlling Kubernetes resources. The actual permissions are defined in the manifests/clusterrole.yaml file.

Complete Cluster Role Permissions¶

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: homeassistant-kubernetes-integration
rules:
# Read permissions for monitoring
- apiGroups: [""]
  resources: ["pods", "nodes", "namespaces"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["extensions"]
  resources: ["deployments", "replicasets"]
  verbs: ["get", "list", "watch"]
# Write permissions for control - including scaling
- apiGroups: ["apps"]
  resources: ["deployments", "deployments/scale", "statefulsets", "statefulsets/scale"]
  verbs: ["patch", "update", "get", "create", "delete"]
- apiGroups: ["extensions"]
  resources: ["deployments", "deployments/scale"]
  verbs: ["patch", "update", "get", "create", "delete"]
# Events for better monitoring and troubleshooting
- apiGroups: [""]
  resources: ["events"]
  verbs: ["get", "list", "watch"]
# StatefulSet status for accurate state reporting
- apiGroups: ["apps"]
  resources: ["statefulsets/status"]
  verbs: ["get", "patch", "update"]
# Batch API permissions for CronJobs
- apiGroups: ["batch"]
  resources: ["cronjobs", "jobs"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["cronjobs", "cronjobs/status", "jobs"]
  verbs: ["get", "patch", "update", "create"]
# Metrics API for real-time CPU and memory usage
- apiGroups: ["metrics.k8s.io"]
  resources: ["nodes", "pods"]
  verbs: ["get", "list"]

Permission Breakdown¶

API Group	Resource	Verbs	Purpose
"" (Core)	pods	`get`, `list`, `watch`	Monitor pod counts and status across namespaces
"" (Core)	nodes	`get`, `list`, `watch`	Monitor cluster nodes count and health
"" (Core)	namespaces	`get`, `list`	List and access namespaces for monitoring
"" (Core)	events	`get`, `list`, `watch`	Access events for troubleshooting and monitoring
apps	deployments	`get`, `list`, `watch`	Monitor deployment status and metadata
apps	deployments/scale	`patch`, `update`, `get`, `create`, `delete`	Scale deployments up/down
apps	replicasets	`get`, `list`, `watch`	Monitor replica sets (underlying deployment resource)
apps	statefulsets	`get`, `list`, `watch`	Monitor statefulset status and metadata
apps	statefulsets/scale	`patch`, `update`, `get`, `create`, `delete`	Scale statefulsets up/down
apps	statefulsets/status	`get`, `patch`, `update`	Update and monitor statefulset status
apps	daemonsets	`get`, `list`, `watch`	Monitor daemonset status and count
batch	cronjobs	`get`, `list`, `watch`	Monitor CronJob status and metadata
batch	cronjobs/status	`get`, `patch`, `update`	Update and monitor CronJob status
batch	jobs	`get`, `list`, `watch`, `create`	Monitor and create jobs (for CronJob triggering)
metrics.k8s.io	nodes	`get`, `list`	Real-time node CPU and memory usage
metrics.k8s.io	pods	`get`, `list`	Workload CPU and memory usage sensors
extensions	deployments	`get`, `list`, `watch`	Legacy API compatibility for older clusters
extensions	deployments/scale	`patch`, `update`, `get`, `create`, `delete`	Legacy scaling API compatibility

Why These Permissions Are Required¶

Monitoring Permissions (`get`, `list`, `watch`)¶

Essential for sensor data: Pod counts, node counts, deployment status
Real-time updates: watch enables efficient real-time monitoring
Cross-namespace visibility: Required when monitoring all namespaces

Control Permissions (`patch`, `update`, `create`, `delete`)¶

Scaling operations: Required to scale deployments and statefulsets
State management: Update resource scales and status
Switch functionality: Enable on/off control of workloads

Legacy API Groups¶

extensions: Provides compatibility with older Kubernetes clusters
Dual API coverage: Ensures the integration works across different cluster versions

Namespace-Specific Setup¶

If you prefer to limit permissions to specific namespaces for enhanced security:

1. Create Service Account in Target Namespace¶

apiVersion: v1
kind: ServiceAccount
metadata:
  name: homeassistant-kubernetes-integration
  namespace: your-target-namespace

2. Create Role (instead of ClusterRole)¶

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: your-target-namespace
  name: homeassistant-kubernetes-integration
rules:
# Monitoring permissions within namespace
- apiGroups: [""]
  resources: ["pods", "events"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
# Control permissions within namespace
- apiGroups: ["apps"]
  resources: ["deployments", "deployments/scale", "statefulsets", "statefulsets/scale"]
  verbs: ["patch", "update", "get"]
- apiGroups: ["apps"]
  resources: ["statefulsets/status"]
  verbs: ["get", "patch", "update"]
# Batch API permissions for CronJobs within namespace
- apiGroups: ["batch"]
  resources: ["cronjobs", "jobs"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["cronjobs", "cronjobs/status", "jobs"]
  verbs: ["get", "patch", "update", "create"]

3. Create RoleBinding (instead of ClusterRoleBinding)¶

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: homeassistant-kubernetes-integration
  namespace: your-target-namespace
subjects:
- kind: ServiceAccount
  name: homeassistant-kubernetes-integration
  namespace: your-target-namespace
roleRef:
  kind: Role
  name: homeassistant-kubernetes-integration
  apiGroup: rbac.authorization.k8s.io

4. Create Token Secret¶

apiVersion: v1
kind: Secret
metadata:
  name: homeassistant-kubernetes-integration-token
  namespace: your-target-namespace
  annotations:
    kubernetes.io/service-account.name: homeassistant-kubernetes-integration
type: kubernetes.io/service-account-token

Limitations of Namespace-Specific Setup¶

No cluster-wide metrics: Cannot see total nodes count or cluster health
No cross-namespace monitoring: Cannot monitor multiple namespaces simultaneously
Limited visibility: Reduced overall cluster insight
Still need namespace permissions: To list namespaces, you'll need at least cluster-level get and list on namespaces

Hybrid Approach: Namespace-Scoped with Minimal Cluster Permissions¶

For a balanced approach, use namespace-scoped roles with minimal cluster permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: homeassistant-kubernetes-integration-minimal
rules:
# Minimal cluster-wide permissions for basic functionality
- apiGroups: [""]
  resources: ["nodes", "namespaces"]
  verbs: ["get", "list"]
- apiGroups: ["batch"]
  resources: ["cronjobs"]
  verbs: ["get", "list"]

Then combine with namespace-specific roles for actual workload control.

Security Considerations¶

Token Security¶

Store the service account token securely in Home Assistant
Regularly rotate service account tokens
Use Kubernetes secrets for token storage

Minimal Permissions¶

The provided RBAC permissions follow the principle of least privilege
Only patch permission is granted for scaling operations
No delete or create permissions are included

Network Security¶

Ensure Home Assistant can reach the Kubernetes API server
Consider using a VPN or private network for API access
Verify SSL certificates are properly configured

Troubleshooting¶

Common Issues¶

Token Extraction Fails

# Check if the secret exists
kubectl get secret homeassistant-kubernetes-integration-token -n homeassistant

# If not found, ensure the service account was created
kubectl get serviceaccount homeassistant-kubernetes-integration -n homeassistant

Permission Denied Errors

# Check the cluster role binding
kubectl get clusterrolebinding homeassistant-kubernetes-integration

# Verify the role permissions
kubectl describe clusterrole homeassistant-kubernetes-integration

Namespace Access Issues

# Test API access with the token
kubectl auth can-i get pods --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

Verification Commands¶

Test your setup with these commands:

# Test basic connectivity
kubectl auth can-i get nodes --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

# Test deployment access
kubectl auth can-i get deployments --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

# Test scaling permissions
kubectl auth can-i patch deployments/scale --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

# Test statefulset scaling
kubectl auth can-i patch statefulsets/scale --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

# Test watch permissions (important for real-time updates)
kubectl auth can-i watch pods --as=system:serviceaccount:homeassistant:homeassistant-kubernetes-integration

Additional Resources¶

RBAC Reference Guide - Comprehensive RBAC permissions documentation and security scenarios
Troubleshooting Guide - Common issues and solutions

Service Account Setup Guide¶

Quick Setup¶

1. Apply Required Manifests¶

2. Extract the Token¶

Step-by-Step Setup¶

1. Create Service Account¶

2. Create Cluster Role¶

3. Create Cluster Role Binding¶

4. Create Token Secret¶

5. Extract the Token¶

RBAC Permissions¶

Complete Cluster Role Permissions¶

Permission Breakdown¶

Why These Permissions Are Required¶

Monitoring Permissions (get, list, watch)¶

Control Permissions (patch, update, create, delete)¶

Legacy API Groups¶

Namespace-Specific Setup¶

1. Create Service Account in Target Namespace¶

2. Create Role (instead of ClusterRole)¶

3. Create RoleBinding (instead of ClusterRoleBinding)¶

4. Create Token Secret¶

Limitations of Namespace-Specific Setup¶

Hybrid Approach: Namespace-Scoped with Minimal Cluster Permissions¶

Security Considerations¶

Token Security¶

Minimal Permissions¶

Network Security¶

Troubleshooting¶

Common Issues¶

Verification Commands¶

Additional Resources¶

Monitoring Permissions (`get`, `list`, `watch`)¶

Control Permissions (`patch`, `update`, `create`, `delete`)¶