homeassistant-operator

README

Home Assistant Operator

A Kubernetes operator that simplifies deploying and managing Home Assistant instances on Kubernetes clusters, with a primary focus on lightweight environments like k3s on Raspberry Pi.

Overview

The Home Assistant Operator automates the deployment and lifecycle management of Home Assistant instances in Kubernetes. Instead of manually creating Deployments, Services, PVCs, and Ingresses, you simply define a HomeAssistant custom resource and the operator handles the rest.

Target Environment

• Primary: k3s on Raspberry Pi 4/5 (ARM64)
• Also supported: Any Kubernetes cluster (AMD64/ARM64)

Project Status

Alpha - The project is in early development. CRDs and APIs may change.

CRD	Status	Description
HomeAssistant	Alpha	Core Home Assistant deployment
HomeAssistantSecrets	Alpha	Declarative secrets management
HomeAssistantConfiguration	Alpha	Declarative configuration with hot-reload
HomeAssistantAutomation	Alpha	Declarative automation management with smart detection & retry
HomeAssistantScene	Alpha	Declarative scene management with smart detection & retry
HomeAssistantScript	Alpha	Declarative script management with smart detection & retry
HomeAssistantIntegration	Alpha	Declarative integration management via Config Flow API

Quick Start

Prerequisites

• Kubernetes cluster (v1.24+)
• kubectl configured to access your cluster
• For development: Go 1.25+, Docker

Installation

1. Install the CRDs:

kubectl apply -f https://raw.githubusercontent.com/przemekhys/homeassistant-operator/main/config/crd/bases/ha.homeassistant.io_homeassistants.yaml

1. Deploy the operator:

kubectl apply -f https://raw.githubusercontent.com/przemekhys/homeassistant-operator/main/dist/install.yaml

1. Create a Home Assistant instance:

See example configurations in config/samples/:

• ha_v1alpha1_homeassistant.yaml - Basic deployment
• ha_v1alpha1_homeassistant_with_bootstrap.yaml - With automatic bootstrap
• ha_v1alpha1_homeassistant_with_config.yaml - With configuration management
• complete_example_with_secrets.yaml - Complete example with secrets

Uninstallation

# Delete Home Assistant instances
kubectl delete homeassistants --all

# Remove CRDs
kubectl delete -f https://raw.githubusercontent.com/przemekhys/homeassistant-operator/main/config/crd/bases/ha.homeassistant.io_homeassistants.yaml

# Remove operator
kubectl delete -f https://raw.githubusercontent.com/przemekhys/homeassistant-operator/main/dist/install.yaml

Development

Building from Source

# Clone the repository
git clone https://github.com/przemekhys/homeassistant-operator.git
cd homeassistant-operator

# Build
make build

# Run tests
make test

# Run linter
make lint

# Build Docker image
make docker-build IMG=myregistry/homeassistant-operator:dev

Local Development with k3d

# Create a test cluster
make k3d-create

# Build and load image into k3d
make k3d-load IMG=controller:latest

# Install CRDs and deploy operator
make install deploy IMG=controller:latest

# Apply sample
kubectl apply -f config/samples/ha_v1alpha1_homeassistant.yaml

# Cleanup
make k3d-delete

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Getting Help

• GitHub Issues: For bugs, feature requests, questions, and community support

Security

This project uses automated security scanning to ensure dependencies are free of known vulnerabilities:

• govulncheck: Scans Go dependencies against the Go Vulnerability Database

  • Runs on every pull request (blocks merge if vulnerabilities found)
  • Local check: make security-check

• Dependabot: Automated dependency updates

  • Weekly scans (Fridays at 23:00 UTC)
  • Automatically creates PRs for security patches
  • Monitors Go modules, GitHub Actions, and Docker dependencies

License

Copyright 2026.

Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Acknowledgments

• Home Assistant - The amazing home automation platform
• Operator SDK - Framework for building Kubernetes operators
• Kubebuilder - SDK for building Kubernetes APIs