API Reference¶

Packages¶

ha.homeassistant.io/v1

ha.homeassistant.io/v1¶

Package v1 contains API Schema definitions for the ha v1 API group.

Resource Types¶

HomeAssistant
HomeAssistantArea
HomeAssistantAreaList
HomeAssistantAutomation
HomeAssistantAutomationList
HomeAssistantConfiguration
HomeAssistantConfigurationList
HomeAssistantFloor
HomeAssistantFloorList
HomeAssistantIntegration
HomeAssistantIntegrationList
HomeAssistantLabel
HomeAssistantLabelList
HomeAssistantList
HomeAssistantScene
HomeAssistantSceneList
HomeAssistantScript
HomeAssistantScriptList
HomeAssistantSecrets
HomeAssistantSecretsList

AlphaSpec¶

AlphaSpec groups experimental fields that are not yet stable enough for the top-level spec. See spec.alpha.* lifecycle: alpha (opt-in, default false) -> stable default false -> stable default true -> mandatory.

Appears in: - HomeAssistantSpec

Field	Description	Validation
`networkPolicy` NetworkPolicyAlphaSpec	NetworkPolicy controls whether the operator creates a NetworkPolicy restricting ingress to the Home Assistant pod.	Optional: {}
`tls` TLSAlphaSpec	TLS groups experimental TLS integration with cert-manager. Native TLS changes the Home Assistant pod networking/config, so it starts in spec.alpha until it stabilizes.	Optional: {}
`devices` DevicePassthroughEntry array	Devices declares host device nodes (e.g. /dev/ttyACM0 for a Zigbee/ Z-Wave USB coordinator) to mount into the Home Assistant container. Each entry is mounted via a hostPath volume typed as a character device; the container is never granted `privileged: true` for this. Declaring at least one entry changes the pod's security context, so this starts in spec.alpha until it stabilizes. This does not affect where the pod is scheduled — the declared device(s) must already exist on whichever node the pod lands on (see node pinning, a separate capability) for this to be useful.	Optional: {}

AutomationAction¶

AutomationAction defines an action to be executed by the automation This is a flexible structure that accepts any valid Home Assistant action configuration

Appears in: - HomeAssistantAutomationSpec

AutomationCondition¶

AutomationCondition defines a condition that must be met for the automation to execute This is a flexible structure that accepts any valid Home Assistant condition configuration

Appears in: - HomeAssistantAutomationSpec

AutomationMode¶

Underlying type: string

AutomationMode defines how the automation should behave when triggered again while already running

Validation: - Enum: [single restart queued parallel]

Appears in: - HomeAssistantAutomationSpec

Field	Description
`single`	AutomationModeSingle - Do not start a new run, issue a warning
`restart`	AutomationModeRestart - Stop previous runs and start a new one
`queued`	AutomationModeQueued - Queue runs in order, sequential execution guaranteed
`parallel`	AutomationModeParallel - Launch independent concurrent runs

AutomationTrigger¶

AutomationTrigger defines an event that will trigger the automation This is a flexible structure that accepts any valid Home Assistant trigger configuration

Appears in: - HomeAssistantAutomationSpec

BackupSpec¶

BackupSpec configures Home Assistant's built-in backup system via WebSocket API.

Appears in: - HomeAssistantSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether automatic backups are configured in HA	false	Optional: {}
`recurrence` string	Recurrence defines how often to create a backup	daily	Enum: [daily mon tue wed thu fri sat sun never] Optional: {}
`time` string	Time is the time of day to create the backup in HH:MM:SS 24-hour format (e.g. "03:00:00"). If empty, Home Assistant picks automatically.		Pattern: `^([01]\d\\|2[0-3]):[0-5]\d:[0-5]\d$` Optional: {}
`retentionCopies` integer	RetentionCopies is the number of backup copies to keep. Nil means unlimited.		Minimum: 1 Optional: {}
`retentionDays` integer	RetentionDays is the number of days to keep backups. Nil means unlimited.		Minimum: 1 Optional: {}
`includeDatabase` boolean	IncludeDatabase controls whether the database is included in the backup.	true	Optional: {}
`agentIDs` string array	AgentIDs is the list of backup agent IDs to use (e.g. "backup.local", "google_drive.my_drive"). Defaults to ["backup.local"] if not specified.		Optional: {}

BootstrapCredentials¶

BootstrapCredentials references a Secret containing admin credentials

Appears in: - BootstrapSpec

Field	Description	Default	Validation
`secretRef` CredentialsSecretRef	SecretRef references a Secret containing username and password

BootstrapSpec¶

BootstrapSpec configures automatic Home Assistant onboarding and API token creation

Appears in: - HomeAssistantSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether automatic bootstrap is performed	false	Optional: {}
`credentials` BootstrapCredentials	Credentials references a Secret containing username and password for the admin user The Secret must have "username" and "password" keys
`createApiToken` boolean	CreateAPIToken controls whether a long-lived access token is created after onboarding The token is valid for 10 years and stored in a Secret	true	Optional: {}
`apiTokenSecretName` string	APITokenSecretName is the name of the Secret where the API token will be stored The Secret will have a "token" key containing the long-lived access token If not specified, defaults to "{homeassistant-name}-homeassistant-api-token"		Optional: {}
`ownerName` string	OwnerName is the display name for the owner user created during onboarding	Admin	Optional: {}
`language` string	Language is the language code for Home Assistant (e.g., "en", "pl")	en	Optional: {}
`location` LocationConfig	Location configures the location settings during onboarding If not specified, location configuration step is skipped		Optional: {}
`analytics` boolean	Analytics controls whether to enable analytics during onboarding If not specified, analytics is disabled by default	false	Optional: {}

BootstrapStatus¶

BootstrapStatus contains the status of the automatic bootstrap process

Appears in: - HomeAssistantStatus

Field	Description	Validation
`completed` boolean	Completed indicates whether the bootstrap process has finished successfully	Optional: {}
`apiTokenReady` boolean	APITokenReady indicates whether the API token has been created and stored	Optional: {}
`apiTokenSecretName` string	APITokenSecretName is the name of the Secret containing the API token	Optional: {}
`lastAttempt` Time	LastAttempt is the timestamp of the last bootstrap attempt	Optional: {}
`message` string	Message provides additional information about the bootstrap status	Optional: {}
`onboardingDoneFirstSeen` Time	OnboardingDoneFirstSeen is the timestamp when /api/onboarding first returned 404. Used to implement confirmation delay without relying on condition LastTransitionTime (which does not update when only the Reason changes).	Optional: {}
`loginRecoveryAttempts` integer	LoginRecoveryAttempts tracks how many times login recovery was attempted. Reset to zero when onboarding is confirmed fresh or bootstrap succeeds.	Optional: {}

ConfigurationReloadStrategy¶

Underlying type: string

ConfigurationReloadStrategy defines how configuration changes should be handled

Validation: - Enum: [auto hot-reload restart]

Appears in: - HomeAssistantConfigurationSpec

Field	Description
`auto`	ConfigurationReloadStrategyAuto - automatically choose best strategy based on config changes
`hot-reload`	ConfigurationReloadStrategyHotReload - attempt to hot-reload via HA REST API
`restart`	ConfigurationReloadStrategyRestart - force full pod restart

CredentialsSecretRef¶

CredentialsSecretRef references a Secret containing username and password credentials

Appears in: - BootstrapCredentials

Field	Description	Default	Validation
`name` string	Name of the Secret
`usernameKey` string	UsernameKey is the key in the Secret containing the username	username	Optional: {}
`passwordKey` string	PasswordKey is the key in the Secret containing the password	password	Optional: {}

DevicePassthroughEntry¶

DevicePassthroughEntry declares one host device node to expose inside the Home Assistant container.

Appears in: - AlphaSpec

Field	Description	Default	Validation
`hostPath` string	HostPath is the device node's path on the host, e.g. /dev/ttyACM0. Must be an absolute path under /dev.		Required: {}
`containerPath` string	ContainerPath is the path the device is mounted at inside the Home Assistant container. Defaults to HostPath when omitted.		Optional: {}

GatewayParentRef¶

GatewayParentRef references an existing Gateway listener.

Appears in: - GatewaySpec

Field	Description	Validation
`name` string	Name of the existing Gateway.
`namespace` string	Namespace of the Gateway. When different from the HA namespace, the user must provide a ReferenceGrant.	Optional: {}
`sectionName` string	SectionName is the listener name (e.g. "https").	Optional: {}

GatewaySpec¶

GatewaySpec configures operator-managed Gateway API exposure for HA. Managing Gateway API routing resources (sibling to the HA pod) is a stable opt-in — it does not change the Home Assistant pod's networking or security context, so it lives at the top level rather than under spec.alpha.

Appears in: - HomeAssistantSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled turns on operator management of Gateway API routing (HTTPRoute, and optionally a Gateway).	false	Optional: {}
`host` string	Host is the hostname for the route and certificate.		Optional: {}
`issuerRef` IssuerReference	IssuerRef references an existing cert-manager Issuer/ClusterIssuer. When set (and cert-manager available), the operator issues a certificate for the listener.		Optional: {}
`secretName` string	SecretName references a bring-your-own TLS Secret for the listener. Takes precedence over IssuerRef.		Optional: {}
`parentRef` GatewayParentRef	ParentRef references an existing Gateway/listener to attach the HTTPRoute to. When empty and ManageGateway is true, the operator creates a Gateway.		Optional: {}
`manageGateway` boolean	ManageGateway controls whether the operator also creates a Gateway resource (not just the HTTPRoute). GatewayClass and the gateway controller remain the platform's responsibility.	false	Optional: {}
`filters` HTTPRouteFilter array	Filters are HTTP route-level behaviors (header modification, redirect, URL rewrite) applied, in order, to the single HTTPRoute rule the operator manages for this instance. Omitted/empty leaves the route unchanged from its default shape.		Optional: {}

HTTPConfig¶

HTTPConfig defines HTTP component configuration

Appears in: - HomeAssistantConfigurationSpec

Field	Description	Validation
`corsDomains` string array	CorsDomains is a list of allowed CORS origins	Optional: {}
`trustProxy` boolean	TrustProxy enables trust in X-Forwarded-For header	Optional: {}
`useXForwardedFor` boolean	UseXForwardedFor enables usage of X-Forwarded-For header	Optional: {}

HTTPHeader¶

HTTPHeader is a single HTTP header name/value pair.

Appears in: - HTTPHeaderFilter

Field	Description	Default	Validation
`name` string	Name of the header.		MinLength: 1 Pattern: `^[A-Za-z0-9!#$%&'*+\-.^_\x60\\|~]+$` Required: {}
`value` string	Value of the header.		MinLength: 1 Required: {}

HTTPHeaderFilter¶

HTTPHeaderFilter adds, sets, or removes HTTP headers. Used for both RequestHeaderModifier and ResponseHeaderModifier.

Appears in: - HTTPRouteFilter

Field	Description	Validation
`set` HTTPHeader array	Set overwrites headers already present.	Optional: {}
`add` HTTPHeader array	Add appends headers, keeping any existing value.	Optional: {}
`remove` string array	Remove lists header names to strip.	Optional: {}

HTTPPathModifier¶

HTTPPathModifier describes a path replacement for HTTPRequestRedirectFilter or HTTPURLRewriteFilter.

Appears in: - HTTPRequestRedirectFilter - HTTPURLRewriteFilter

Field	Description	Validation
`type` string	Type selects which of the fields below applies.	Enum: [ReplaceFullPath ReplacePrefixMatch] Required: {}
`replaceFullPath` string	ReplaceFullPath is the whole replacement path. Must be set, and only be set, when Type is ReplaceFullPath.	Optional: {}
`replacePrefixMatch` string	ReplacePrefixMatch is the replacement for the matched path prefix. Must be set, and only be set, when Type is ReplacePrefixMatch.	Optional: {}

HTTPRequestRedirectFilter¶

HTTPRequestRedirectFilter redirects the request to a different scheme/hostname/path/port, optionally with a specific status code.

Appears in: - HTTPRouteFilter

Field	Description	Validation
`scheme` string	Scheme replaces the request scheme (e.g. "https").	Optional: {}
`hostname` string	Hostname replaces the request hostname.	Optional: {}
`path` HTTPPathModifier	Path replaces the request path.	Optional: {}
`port` integer	Port replaces the request port.	Optional: {}
`statusCode` integer	StatusCode is the redirect status code.	Enum: [301 302 303 307 308] Optional: {}

HTTPRouteFilter¶

HTTPRouteFilter is one user-declared route behavior attached to the HTTP route exposing a HomeAssistant instance through Gateway API. Mirrors the field names/shape of upstream Gateway API's own HTTPRouteFilter, limited to the four supported types: RequestHeaderModifier, ResponseHeaderModifier, RequestRedirect, URLRewrite. Exactly the sub-object matching Type must be set; the webhook rejects any other combination.

Appears in: - GatewaySpec

Field	Description	Validation
`type` string	Type selects which of the sub-objects below applies.	Enum: [RequestHeaderModifier ResponseHeaderModifier RequestRedirect URLRewrite] Required: {}
`requestHeaderModifier` HTTPHeaderFilter	RequestHeaderModifier modifies request headers. Must be set, and only be set, when Type is RequestHeaderModifier.	Optional: {}
`responseHeaderModifier` HTTPHeaderFilter	ResponseHeaderModifier modifies response headers. Must be set, and only be set, when Type is ResponseHeaderModifier.	Optional: {}
`requestRedirect` HTTPRequestRedirectFilter	RequestRedirect redirects the request. Must be set, and only be set, when Type is RequestRedirect.	Optional: {}
`urlRewrite` HTTPURLRewriteFilter	URLRewrite rewrites the request path/hostname. Must be set, and only be set, when Type is URLRewrite.	Optional: {}

HTTPURLRewriteFilter¶

HTTPURLRewriteFilter rewrites the request hostname/path before it reaches Home Assistant.

Appears in: - HTTPRouteFilter

Field	Description	Default	Validation
`hostname` string	Hostname replaces the request hostname.		Optional: {}
`path` HTTPPathModifier	Path replaces the request path.		Optional: {}

HomeAssistant¶

HomeAssistant is the Schema for the homeassistants API.

Appears in: - HomeAssistantList

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistant`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HomeAssistantSpec
`status` HomeAssistantStatus

HomeAssistantArea¶

HomeAssistantArea is the Schema for the homeassistantareas API

Appears in: - HomeAssistantAreaList

Field	Description	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantArea`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` HomeAssistantAreaSpec		Required: {}
`status` HomeAssistantAreaStatus		Optional: {}

HomeAssistantAreaList¶

HomeAssistantAreaList contains a list of HomeAssistantArea

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantAreaList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantArea array

HomeAssistantAreaSpec¶

HomeAssistantAreaSpec defines the desired state of HomeAssistantArea

Appears in: - HomeAssistantArea

Field	Description	Validation
`homeAssistantRef` HomeAssistantReference	homeAssistantRef is a reference to the HomeAssistant CR this area belongs to	Required: {}
`name` string	name is the display name of the area in Home Assistant	MinLength: 1 Required: {}
`floorName` string	floorName is the name of the HomeAssistantFloor CR to assign this area to (resolved at reconcile time)	Optional: {}
`icon` string	icon is the Material Design Icon for the area (e.g. "mdi:sofa")	Optional: {}
`labels` string array	labels is a list of HomeAssistantLabel CR names to assign to this area (resolved at reconcile time)	Optional: {}

HomeAssistantAreaStatus¶

HomeAssistantAreaStatus defines the observed state of HomeAssistantArea

Appears in: - HomeAssistantArea

Field	Description	Validation
`areaID` string	areaID is the ID assigned by Home Assistant after creation	Optional: {}
`observedGeneration` integer	observedGeneration is the most recent generation observed	Optional: {}
`lastError` string	lastError contains the error message from the last failed operation Cleared when operation succeeds	Optional: {}
`conditions` Condition array	conditions represent the current state of the HomeAssistantArea resource	Optional: {}

HomeAssistantAutomation¶

HomeAssistantAutomation is the Schema for the homeassistantautomations API

Appears in: - HomeAssistantAutomationList

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantAutomation`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HomeAssistantAutomationSpec
`status` HomeAssistantAutomationStatus

HomeAssistantAutomationList¶

HomeAssistantAutomationList contains a list of HomeAssistantAutomation

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantAutomationList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantAutomation array

HomeAssistantAutomationSpec¶

HomeAssistantAutomationSpec defines the desired state of HomeAssistantAutomation

Appears in: - HomeAssistantAutomation

Field	Description	Default	Validation
`homeAssistantRef` HomeAssistantReference	HomeAssistantRef references the HomeAssistant CR that will use this automation		Required: {}
`id` string	ID is a unique identifier for the automation (used by Home Assistant) If not specified, will be auto-generated from the CR name Must contain only lowercase letters, digits, and underscores. Existing resources with an id predating this constraint (uppercase letters or hyphens) keep working until their next update, which will then be rejected until id is renamed to a conforming value.		Pattern: `^[a-z][a-z0-9_]*$` Optional: {}
`alias` string	Alias is a user-friendly name for the automation		MinLength: 1 Required: {}
`description` string	Description provides details about what the automation does		Optional: {}
`triggers` AutomationTrigger array	Triggers define the events that will trigger this automation At least one trigger is required		MinItems: 1 Required: {}
`conditions` AutomationCondition array	Conditions define requirements that must be met for the automation to execute All conditions must evaluate to true for the automation to run		Optional: {}
`actions` AutomationAction array	Actions define the sequence of tasks to execute when triggered At least one action is required		MinItems: 1 Required: {}
`mode` AutomationMode	Mode defines how the automation should behave when triggered again while already running	single	Enum: [single restart queued parallel] Optional: {}
`max` integer	Max defines the maximum number of concurrent or queued runs (for queued/parallel modes)	10	Minimum: 1 Optional: {}
`maxExceeded` string	MaxExceeded defines the log severity level when max is exceeded (silent, info, warning, error)	warning	Enum: [silent info warning error] Optional: {}
`initialState` boolean	InitialState defines whether the automation should be enabled at startup If not specified, the last state is restored		Optional: {}
`autoReload` boolean	AutoReload enables automatic hot-reload when automation changes If false, requires manual reload or pod restart	true	Optional: {}
`enabled` boolean	Enabled controls whether this automation is active Can be used to temporarily disable without deleting the CR	true	Optional: {}

HomeAssistantAutomationStatus¶

HomeAssistantAutomationStatus defines the observed state of HomeAssistantAutomation

Appears in: - HomeAssistantAutomation

Field	Description	Validation
`conditions` Condition array	Conditions represent the latest available observations of the HomeAssistantAutomation state	Optional: {}
`automationHash` string	AutomationHash is the SHA256 hash of the current automation configuration Used to detect changes and determine if reload is needed	Optional: {}
`lastReloadTime` Time	LastReloadTime is the timestamp of the last successful reload	Optional: {}
`lastTriggeredTime` Time	LastTriggeredTime is the timestamp when the automation was last triggered (if available from HA)	Optional: {}
`lastError` string	LastError contains the error message from the last failed operation Cleared when operation succeeds	Optional: {}
`lastReloadMethod` string	LastReloadMethod indicates how the last reload was performed Possible values: "hot-reload", "restart", "none"	Optional: {}
`observedGeneration` integer	ObservedGeneration reflects the generation of the most recently observed HomeAssistantAutomation	Optional: {}

HomeAssistantConfiguration¶

HomeAssistantConfiguration is the Schema for the homeassistantconfigurations API.

Appears in: - HomeAssistantConfigurationList

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantConfiguration`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HomeAssistantConfigurationSpec
`status` HomeAssistantConfigurationStatus

HomeAssistantConfigurationList¶

HomeAssistantConfigurationList contains a list of HomeAssistantConfiguration.

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantConfigurationList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantConfiguration array

HomeAssistantConfigurationSpec¶

HomeAssistantConfigurationSpec defines the desired state of HomeAssistantConfiguration

Appears in: - HomeAssistantConfiguration

Field	Description	Default	Validation
`homeAssistantRef` HomeAssistantReference	HomeAssistantRef references the HomeAssistant CR that will use this configuration		Required: {}
`configuration` string	Configuration contains the full configuration.yaml content as a string This is the raw YAML configuration for Home Assistant		Required: {}
`reloadStrategy` ConfigurationReloadStrategy	ReloadStrategy defines how configuration changes should be applied	auto	Enum: [auto hot-reload restart] Optional: {}
`autoReload` boolean	AutoReload enables automatic reloading/restart when configuration changes	true	Optional: {}
`http` HTTPConfig	HTTP component configuration (optional typed section)		Optional: {}
`logger` LoggerConfig	Logger component configuration (optional typed section)		Optional: {}
`recorder` RecorderConfig	Recorder component configuration (optional typed section)		Optional: {}
`mqtt` MQTTConfig	MQTT component configuration (optional typed section)		Optional: {}

HomeAssistantConfigurationStatus¶

HomeAssistantConfigurationStatus defines the observed state of HomeAssistantConfiguration

Appears in: - HomeAssistantConfiguration

Field	Description	Validation
`conditions` Condition array	Conditions represent the latest available observations of the HomeAssistantConfiguration state	Optional: {}
`configHash` string	ConfigHash is the SHA256 hash of the current configuration Used to detect changes and determine if reload is needed	Optional: {}
`lastReloadTime` Time	LastReloadTime is the timestamp of the last successful reload/restart	Optional: {}
`lastReloadMethod` string	LastReloadMethod indicates how the last reload was performed (hot-reload or restart)	Optional: {}
`lastError` string	LastError contains the error message from the last failed reload attempt Cleared when reload succeeds	Optional: {}
`observedGeneration` integer	Generation tracks the generation of the spec that the status reflects	Optional: {}
`trustedProxiesDefaulted` boolean	TrustedProxiesDefaulted reports whether the operator's default http.trusted_proxies / http.use_x_forwarded_for values are currently active in the generated configuration for the referenced HomeAssistant. false covers every case where they are not active (not exposed via Ingress/Gateway, opted out via spec.disableDefaultTrustedProxies, or the user already manages these keys themselves) — see the HomeAssistant's own ExposureReady condition message for which of those it is.	Optional: {}

HomeAssistantFloor¶

HomeAssistantFloor is the Schema for the homeassistantfloors API

Appears in: - HomeAssistantFloorList

Field	Description	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantFloor`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` HomeAssistantFloorSpec		Required: {}
`status` HomeAssistantFloorStatus		Optional: {}

HomeAssistantFloorList¶

HomeAssistantFloorList contains a list of HomeAssistantFloor

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantFloorList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantFloor array

HomeAssistantFloorSpec¶

HomeAssistantFloorSpec defines the desired state of HomeAssistantFloor

Appears in: - HomeAssistantFloor

Field	Description	Validation
`homeAssistantRef` HomeAssistantReference	homeAssistantRef is a reference to the HomeAssistant CR this floor belongs to	Required: {}
`name` string	name is the display name of the floor in Home Assistant	MinLength: 1 Required: {}
`level` integer	level is the floor level (e.g. 0 for ground, 1 for first, -1 for basement)	Optional: {}
`icon` string	icon is the Material Design Icon for the floor (e.g. "mdi:home-floor-1")	Optional: {}

HomeAssistantFloorStatus¶

HomeAssistantFloorStatus defines the observed state of HomeAssistantFloor

Appears in: - HomeAssistantFloor

Field	Description	Validation
`floorID` string	floorID is the ID assigned by Home Assistant after creation	Optional: {}
`observedGeneration` integer	observedGeneration is the most recent generation observed	Optional: {}
`lastError` string	lastError contains the error message from the last failed operation Cleared when operation succeeds	Optional: {}
`conditions` Condition array	conditions represent the current state of the HomeAssistantFloor resource	Optional: {}

HomeAssistantIntegration¶

HomeAssistantIntegration manages a Home Assistant integration (config entry) via the Config Flow API. It supports create, adopt, reconfigure (delete+re-create on spec change), and cleanup via finalizer. Only single-step Config Flows are supported (e.g. mqtt, recorder, esphome).

Appears in: - HomeAssistantIntegrationList

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantIntegration`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HomeAssistantIntegrationSpec
`status` HomeAssistantIntegrationStatus

HomeAssistantIntegrationList¶

HomeAssistantIntegrationList contains a list of HomeAssistantIntegration

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantIntegrationList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantIntegration array

HomeAssistantIntegrationSpec¶

HomeAssistantIntegrationSpec defines the desired state of HomeAssistantIntegration

Appears in: - HomeAssistantIntegration

Field	Description	Validation
`homeAssistantRef` HomeAssistantReference	HomeAssistantRef references the HomeAssistant instance to configure	Required: {}
`domain` string	Domain is the integration name in Home Assistant (e.g. "mqtt", "esphome", "recorder")	MinLength: 1 Required: {}
`configuration` object (keys:string, values:IntegrationValue)	Configuration contains fields submitted to the Config Flow (single-step flows only). Keys are field names from the data_schema; values are plain text or Secret references.	Optional: {}

HomeAssistantIntegrationStatus¶

HomeAssistantIntegrationStatus defines the observed state of HomeAssistantIntegration

Appears in: - HomeAssistantIntegration

Field	Description	Validation
`entryID` string	EntryID is the Home Assistant config entry ID created or adopted by the Config Flow	Optional: {}
`configHash` string	ConfigHash is the SHA256 hash of the resolved configuration values. Used to detect spec changes and trigger reconfiguration (delete + re-create).	Optional: {}
`conditions` Condition array	Conditions represent the latest available observations of the integration state	Optional: {}
`lastError` string	LastError contains the error message from the last failed operation Cleared when operation succeeds	Optional: {}
`observedGeneration` integer	ObservedGeneration reflects the generation of the most recently observed CR	Optional: {}

HomeAssistantLabel¶

HomeAssistantLabel is the Schema for the homeassistantlabels API

Appears in: - HomeAssistantLabelList

Field	Description	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantLabel`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` HomeAssistantLabelSpec		Required: {}
`status` HomeAssistantLabelStatus		Optional: {}

HomeAssistantLabelList¶

HomeAssistantLabelList contains a list of HomeAssistantLabel

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantLabelList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantLabel array

HomeAssistantLabelSpec¶

HomeAssistantLabelSpec defines the desired state of HomeAssistantLabel

Appears in: - HomeAssistantLabel

Field	Description	Validation
`homeAssistantRef` HomeAssistantReference	homeAssistantRef is a reference to the HomeAssistant CR this label belongs to	Required: {}
`name` string	name is the display name of the label in Home Assistant	MinLength: 1 Required: {}
`icon` string	icon is the Material Design Icon for the label (e.g. "mdi:tag")	Optional: {}
`color` string	color is the label color (e.g. "red", "blue", "green")	Optional: {}

HomeAssistantLabelStatus¶

HomeAssistantLabelStatus defines the observed state of HomeAssistantLabel

Appears in: - HomeAssistantLabel

Field	Description	Validation
`labelID` string	labelID is the ID assigned by Home Assistant after creation	Optional: {}
`observedGeneration` integer	observedGeneration is the most recent generation observed	Optional: {}
`lastError` string	lastError contains the error message from the last failed operation Cleared when operation succeeds	Optional: {}
`conditions` Condition array	conditions represent the current state of the HomeAssistantLabel resource	Optional: {}

HomeAssistantList¶

HomeAssistantList contains a list of HomeAssistant.

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistant array

HomeAssistantPhase¶

Underlying type: string

HomeAssistantPhase represents the current phase of the HomeAssistant instance.

Validation: - Enum: [Pending Running Failed Unknown]

Appears in: - HomeAssistantStatus

Field	Description
`Pending`
`Running`
`Failed`
`Unknown`

HomeAssistantReference¶

HomeAssistantReference references a HomeAssistant CR.

Appears in: - HomeAssistantAreaSpec - HomeAssistantAutomationSpec - HomeAssistantConfigurationSpec - HomeAssistantFloorSpec - HomeAssistantIntegrationSpec - HomeAssistantLabelSpec - HomeAssistantSceneSpec - HomeAssistantScriptSpec - HomeAssistantSecretsSpec

Field	Description	Default	Validation
`name` string	Name of the HomeAssistant resource		MinLength: 1 Required: {}

HomeAssistantScene¶

HomeAssistantScene is the Schema for the homeassistantscenes API

Appears in: - HomeAssistantSceneList

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantScene`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HomeAssistantSceneSpec
`status` HomeAssistantSceneStatus

HomeAssistantSceneList¶

HomeAssistantSceneList contains a list of HomeAssistantScene

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantSceneList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantScene array

HomeAssistantSceneSpec¶

HomeAssistantSceneSpec defines the desired state of HomeAssistantScene

Appears in: - HomeAssistantScene

Field	Description	Default	Validation
`homeAssistantRef` HomeAssistantReference	HomeAssistantRef references the HomeAssistant CR that will use this scene		Required: {}
`id` string	ID is a unique identifier for the scene (used by Home Assistant) If not specified, will be auto-generated from the CR name Must contain only lowercase letters, digits, and underscores. Existing resources with an id predating this constraint (uppercase letters or hyphens) keep working until their next update, which will then be rejected until id is renamed to a conforming value.		Pattern: `^[a-z][a-z0-9_]*$` Optional: {}
`name` string	Name is a user-friendly name for the scene (displayed in Home Assistant UI) If not specified, the CR name will be used		MinLength: 1 Optional: {}
`icon` string	Icon is a Material Design icon for the scene (e.g., "mdi:movie", "mdi:candle") See https://mdi.bessarabov.com/ for available icons		Optional: {}
`entities` SceneEntity array	Entities define the list of devices and their states to set when scene is activated At least one entity is required		MinItems: 1 Required: {}
`autoReload` boolean	AutoReload enables automatic hot-reload when scene configuration changes If false, requires manual reload or pod restart	true	Optional: {}

HomeAssistantSceneStatus¶

HomeAssistantSceneStatus defines the observed state of HomeAssistantScene

Appears in: - HomeAssistantScene

Field	Description	Validation
`conditions` Condition array	Conditions represent the latest available observations of the HomeAssistantScene state	Optional: {}
`sceneHash` string	SceneHash is the SHA256 hash of the current scene configuration Used to detect changes and determine if reload is needed	Optional: {}
`lastReloadTime` Time	LastReloadTime is the timestamp of the last successful reload	Optional: {}
`lastActivated` Time	LastActivated is the timestamp when the scene was last activated (if available from HA)	Optional: {}
`lastError` string	LastError contains the error message from the last failed operation Cleared when operation succeeds	Optional: {}
`entityCount` integer	EntityCount is the number of entities defined in the scene Updated by the controller for display in kubectl output	Optional: {}
`observedGeneration` integer	ObservedGeneration reflects the generation of the most recently observed HomeAssistantScene	Optional: {}

HomeAssistantScript¶

HomeAssistantScript is the Schema for the homeassistantscripts API

Appears in: - HomeAssistantScriptList

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantScript`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HomeAssistantScriptSpec
`status` HomeAssistantScriptStatus

HomeAssistantScriptList¶

HomeAssistantScriptList contains a list of HomeAssistantScript

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantScriptList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantScript array

HomeAssistantScriptSpec¶

HomeAssistantScriptSpec defines the desired state of HomeAssistantScript

Appears in: - HomeAssistantScript

Field	Description	Default	Validation
`homeAssistantRef` HomeAssistantReference	HomeAssistantRef references the HomeAssistant CR that will use this script		Required: {}
`id` string	ID is a unique identifier for the script (used by Home Assistant) If not specified, will be auto-generated from the CR name Must contain only lowercase letters, digits, and underscores		Pattern: `^[a-z][a-z0-9_]*$` Optional: {}
`alias` string	Alias is a user-friendly name for the script		MinLength: 1 Required: {}
`description` string	Description provides details about what the script does		Optional: {}
`icon` string	Icon is a Material Design icon for the script (e.g., "mdi:script", "mdi:play") See https://mdi.bessarabov.com/ for available icons		Optional: {}
`sequence` ScriptAction array	Sequence defines the list of actions to execute when the script is called At least one action is required		MinItems: 1 Required: {}
`fields` object (keys:string, values:ScriptField)	Fields define input parameters for the script These allow the script to accept arguments when called		Optional: {}
`mode` ScriptMode	Mode defines how the script should behave when called again while already running	single	Enum: [single restart queued parallel] Optional: {}
`max` integer	Max defines the maximum number of concurrent or queued runs (for queued/parallel modes)	10	Minimum: 1 Optional: {}
`maxExceeded` string	MaxExceeded defines the log severity level when max is exceeded (silent, info, warning, error)	warning	Enum: [silent info warning error] Optional: {}
`autoReload` boolean	AutoReload enables automatic hot-reload when script changes If false, requires manual reload or pod restart	true	Optional: {}

HomeAssistantScriptStatus¶

HomeAssistantScriptStatus defines the observed state of HomeAssistantScript

Appears in: - HomeAssistantScript

Field	Description	Validation
`conditions` Condition array	Conditions represent the latest available observations of the HomeAssistantScript state	Optional: {}
`scriptHash` string	ScriptHash is the SHA256 hash of the current script configuration Used to detect changes and determine if reload is needed	Optional: {}
`lastReloadTime` Time	LastReloadTime is the timestamp of the last successful reload	Optional: {}
`lastRunTime` Time	LastRunTime is the timestamp when the script was last executed (if available from HA)	Optional: {}
`lastError` string	LastError contains the error message from the last failed operation Cleared when operation succeeds	Optional: {}
`lastReloadMethod` string	LastReloadMethod indicates how the last reload was performed Possible values: "hot-reload" (success), "failed" (all retries exhausted), "none" (skipped/initial)	Optional: {}
`observedGeneration` integer	ObservedGeneration reflects the generation of the most recently observed HomeAssistantScript	Optional: {}

HomeAssistantSecrets¶

HomeAssistantSecrets is the Schema for the homeassistantsecrets API.

Appears in: - HomeAssistantSecretsList

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantSecrets`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` HomeAssistantSecretsSpec
`status` HomeAssistantSecretsStatus

HomeAssistantSecretsList¶

HomeAssistantSecretsList contains a list of HomeAssistantSecrets.

Field	Description	Default	Validation
`apiVersion` string	`ha.homeassistant.io/v1`
`kind` string	`HomeAssistantSecretsList`
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` HomeAssistantSecrets array

HomeAssistantSecretsSpec¶

HomeAssistantSecretsSpec defines the desired state of HomeAssistantSecrets.

Appears in: - HomeAssistantSecrets

Field	Description	Default	Validation
`homeAssistantRef` HomeAssistantReference	HomeAssistantRef references the HomeAssistant CR that will use these secrets		Required: {}
`secretRefs` SecretKeyReference array	SecretRefs is a list of references to Kubernetes Secrets. Keys from these Secrets will be merged into the generated secrets.yaml		MinItems: 1 Required: {}
`autoRestart` boolean	AutoRestart controls whether the Home Assistant pod should be automatically restarted when secrets change. When enabled, the controller updates an annotation on the StatefulSet to trigger a rolling restart.	true	Optional: {}

HomeAssistantSecretsStatus¶

HomeAssistantSecretsStatus defines the observed state of HomeAssistantSecrets.

Appears in: - HomeAssistantSecrets

Field	Description	Validation
`conditions` Condition array	Conditions represent the latest available observations of the HomeAssistantSecrets state	Optional: {}
`secretsHash` string	SecretsHash is the SHA256 hash of the generated secrets.yaml content. Used to detect changes and trigger pod restarts.	Optional: {}
`lastUpdated` Time	LastUpdated is the timestamp when the secrets were last updated	Optional: {}
`observedGeneration` integer	ObservedGeneration reflects the generation of the most recently observed HomeAssistantSecrets	Optional: {}
`lastError` string	LastError contains a human-readable description of the last error encountered	Optional: {}

HomeAssistantSpec¶

HomeAssistantSpec defines the desired state of HomeAssistant.

Appears in: - HomeAssistant

Field	Description	Default	Validation
`version` string	Version is the Home Assistant version/tag to deploy (e.g., "2024.1.0", "stable", "latest")	stable	Optional: {}
`image` string	Image allows overriding the default Home Assistant image	ghcr.io/home-assistant/home-assistant	Optional: {}
`storage` StorageSpec	Storage configuration for Home Assistant data		Optional: {}
`resources` ResourceRequirements	Resources defines CPU and memory requests/limits		Optional: {}
`service` ServiceSpec	Service configuration for exposing Home Assistant		Optional: {}
`ingress` IngressSpec	Ingress configuration for external access		Optional: {}
`gateway` GatewaySpec	Gateway configures operator-managed Gateway API exposure (HTTPRoute, and optionally a Gateway) for Home Assistant, with optional cert-manager TLS.		Optional: {}
`timezone` string	Timezone for the Home Assistant instance (e.g., "Europe/Warsaw")	UTC	Optional: {}
`secretsFrom` SecretReference	SecretsFrom references a Secret containing secrets.yaml The Secret should have a key "secrets.yaml" with the HA secrets		Optional: {}
`hostNetwork` boolean	HostNetwork enables host networking for the Home Assistant pod. When true, the pod uses the host's network namespace, enabling discovery of IoT devices via mDNS, SSDP, and DHCP on the local network.		Optional: {}
`bootstrap` BootstrapSpec	Bootstrap configures automatic onboarding and API token creation When enabled, the operator will automatically complete the Home Assistant onboarding process and create a long-lived access token for API access		Optional: {}
`backup` BackupSpec	Backup configures automatic backups using Home Assistant's built-in backup system. Requires bootstrap with API token enabled.		Optional: {}
`disableDefaultTrustedProxies` boolean	DisableDefaultTrustedProxies opts out of the operator's automatic http.trusted_proxies / http.use_x_forwarded_for defaults. When Ingress or Gateway API exposure is enabled, Home Assistant rejects every request through that endpoint with 400 Bad Request until it trusts the proxy forwarding the request. Unless this is set to true, and unless the user has already set these keys themselves in HomeAssistantConfiguration (or manages http: entirely externally, e.g. via an !include tag), the operator injects the RFC1918 private address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) as sensible defaults — this cannot be a reliable autodetection of the real cluster CIDR, only a conservative guess, so this field exists to opt out entirely for clusters where it doesn't apply (e.g. non-RFC1918 pod/service networks, or where other workloads on the pod network should not be trusted to set X-Forwarded-For for the actual Ingress/Gateway proxy).		Optional: {}
`scheduling` SchedulingSpec	Scheduling controls where the Home Assistant pod is eligible to run and how it is treated under resource contention, using Kubernetes' own well-tested scheduling primitives directly (node selector, node/pod affinity and anti-affinity, tolerations, priority class) rather than a project-specific abstraction. Ships on the stable spec (not spec.alpha.*): the operator only passes these fields through to the generated pod template unchanged, it does not implement any new scheduling behavior of its own.		Optional: {}
`alpha` AlphaSpec	Alpha groups experimental, unstable fields. Fields here may change or be removed without a deprecation notice.		Optional: {}

HomeAssistantStatus¶

HomeAssistantStatus defines the observed state of HomeAssistant.

Appears in: - HomeAssistant

Field	Description	Validation
`phase` HomeAssistantPhase	Phase represents the current lifecycle phase of the HomeAssistant instance	Enum: [Pending Running Failed Unknown] Optional: {}
`conditions` Condition array	Conditions represent the latest available observations of the HomeAssistant state	Optional: {}
`version` string	Version is the currently deployed Home Assistant version	Optional: {}
`url` string	URL is the access URL for Home Assistant (if Ingress is enabled)	Optional: {}
`ready` boolean	Ready indicates if the Home Assistant instance is ready to serve traffic	Optional: {}
`observedGeneration` integer	ObservedGeneration reflects the generation of the most recently observed HomeAssistant	Optional: {}
`bootstrap` BootstrapStatus	BootstrapStatus contains the status of the automatic bootstrap process	Optional: {}
`selfUnbanCount` integer	SelfUnbanCount is the total number of ban-recovery pod restarts. Kept for backwards compatibility; prefer BanRestartWindowCount for limit enforcement.	Optional: {}
`lastSelfUnban` Time	LastSelfUnban is the timestamp of the most recent ban-recovery pod restart.	Optional: {}
`banRestartWindowStart` Time	BanRestartWindowStart is the start of the current ban-recovery sliding window. Nil means no window is active (no ban seen or window has expired).	Optional: {}
`banRestartWindowCount` integer	BanRestartWindowCount is the number of ban-recovery pod restarts within the current sliding window. When it reaches banRestartMaxCount the operator stops restarting and sets condition BanRecoveryFailed=True.	Optional: {}

IngressSpec¶

IngressSpec defines external access configuration.

Appears in: - HomeAssistantSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether an Ingress resource is created	false	Optional: {}
`host` string	Host is the hostname for the Ingress (e.g., "ha.example.com")		Optional: {}
`ingressClassName` string	IngressClassName specifies the Ingress controller to use		Optional: {}
`tls` IngressTLSSpec	TLS configuration		Optional: {}
`annotations` object (keys:string, values:string)	Annotations to add to the Ingress resource		Optional: {}

IngressTLSSpec¶

IngressTLSSpec defines TLS configuration for Ingress.

Appears in: - IngressSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether TLS is enabled	false	Optional: {}
`secretName` string	SecretName containing the TLS certificate. When set, it is used as-is (bring-your-own) and takes precedence over IssuerRef.		Optional: {}
`issuerRef` IssuerReference	IssuerRef references an existing cert-manager Issuer/ClusterIssuer. When set and cert-manager is available, the operator creates a Certificate for the Ingress TLS Secret. Ignored when SecretName is provided.		Optional: {}

InitContainerSpec¶

InitContainerSpec configures the image used for the config-init init container.

Appears in: - StorageSpec

Field	Description	Default	Validation
`repository` string	Repository is the container image repository (e.g. "docker.io/library")	docker.io/library	Optional: {}
`image` string	Image is the container image name (e.g. "busybox")	busybox	Optional: {}
`tag` string	Tag is the container image tag (e.g. "1.36", "latest")	1.36	Optional: {}

IntegrationSecretKeyRef¶

IntegrationSecretKeyRef references a specific key within a Kubernetes Secret

Appears in: - IntegrationValue

Field	Description	Default	Validation
`name` string	Name of the Secret		MinLength: 1
`key` string	Key within the Secret		MinLength: 1

IntegrationValue¶

IntegrationValue holds a plain text value, a JSON value, or a reference to a Kubernetes Secret key. Exactly one of Value, JSONValue, or SecretKeyRef must be set.

Appears in: - HomeAssistantIntegrationSpec

Field	Description	Validation
`value` string	Value is a plain text configuration value sent as a string to the Config Flow API.	Optional: {}
`jsonValue` string	JSONValue is a JSON-encoded value that will be parsed and sent as a native JSON object to the Config Flow API. Use this for fields that expect a dictionary or array (e.g. location: '{"latitude": 54.17, "longitude": 18.55}').	Optional: {}
`secretKeyRef` IntegrationSecretKeyRef	SecretKeyRef references a key in a Kubernetes Secret	Optional: {}

IssuerReference¶

IssuerReference references a cert-manager Issuer or ClusterIssuer. The operator only references issuers — it never creates application issuers.

Appears in: - GatewaySpec - IngressTLSSpec - NativeTLSAlphaSpec

Field	Description	Default	Validation
`name` string	Name of the Issuer/ClusterIssuer.
`kind` string	Kind of the issuer.	Issuer	Enum: [Issuer ClusterIssuer] Optional: {}
`group` string	Group of the issuer API.	cert-manager.io	Optional: {}

LocationConfig¶

LocationConfig defines location settings for Home Assistant onboarding

Appears in: - BootstrapSpec

Field	Description	Default	Validation
`name` string	Name is the location name (e.g., "Home", "Warsaw")		Optional: {}
`latitude` string	Latitude in decimal degrees (e.g., "52.2297")		Pattern: `^-?([0-8]?[0-9](\.[0-9]+)?\\|90(\.0+)?)$` Optional: {}
`longitude` string	Longitude in decimal degrees (e.g., "21.0122")		Pattern: `^-?(1[0-7][0-9](\.[0-9]+)?\\|[0-9]\{1,2\}(\.[0-9]+)?\\|180(\.0+)?)$` Optional: {}
`elevation` integer	Elevation in meters		Optional: {}
`unitSystem` string	UnitSystem defines the unit system ("metric" or "us_customary")	metric	Enum: [metric us_customary] Optional: {}
`currency` string	Currency is the ISO 4217 currency code (e.g., "USD", "EUR", "PLN")		Optional: {}
`timeZone` string	TimeZone is the IANA timezone (e.g., "Europe/Warsaw", "America/New_York") If not specified, uses spec.timezone		Optional: {}

LoggerConfig¶

LoggerConfig defines logging component configuration

Appears in: - HomeAssistantConfigurationSpec

Field	Description	Default	Validation
`defaultLevel` string	DefaultLevel is the default logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)	INFO	Optional: {}
`logs` object (keys:string, values:string)	Logs is a map of component names to their logging levels Example: {"homeassistant.core": "DEBUG", "homeassistant.components.mqtt": "DEBUG"}		Optional: {}

MQTTConfig¶

MQTTConfig defines MQTT component configuration

Appears in: - HomeAssistantConfigurationSpec

Field	Description	Default	Validation
`broker` string	Broker is the MQTT broker address (e.g., "mqtt://localhost:1883")		Required: {}
`username` string	Username for MQTT authentication		Optional: {}
`passwordRef` SecretKeySelector	PasswordRef references a Secret containing the MQTT password The Secret should have a "password" key		Optional: {}
`clientID` string	ClientID for MQTT connection		Optional: {}
`keepAlive` integer	KeepAlive defines MQTT keep-alive interval in seconds	60	Optional: {}

NativeTLSAlphaSpec¶

NativeTLSAlphaSpec configures native TLS termination inside Home Assistant.

Appears in: - TLSAlphaSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled turns on native TLS. Home Assistant serves HTTPS on its existing port (8123); the Service port is unchanged. Requires cert-manager to be installed (or a bring-your-own SecretName). When cert-manager is absent, the operator reports a status condition and keeps serving HTTP. Deliberately without omitempty (see NetworkPolicyAlphaSpec.Enabled).	false	Optional: {}
`issuerRef` IssuerReference	IssuerRef references an existing cert-manager Issuer/ClusterIssuer used to issue the certificate. Required unless SecretName (bring-your-own) is set.		Optional: {}
`dnsNames` string array	DNSNames are additional SANs for the certificate. The operator always adds the in-cluster Service FQDN so it can trust HA over HTTPS.		Optional: {}
`secretName` string	SecretName references a user-provided TLS Secret (bring-your-own). When set, the operator does not create a cert-manager Certificate and this Secret takes precedence over IssuerRef.		Optional: {}

NetworkPolicyAlphaSpec¶

NetworkPolicyAlphaSpec configures the (alpha) NetworkPolicy created for the Home Assistant pod.

Appears in: - AlphaSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether the operator creates a NetworkPolicy for the Home Assistant pod, restricting ingress to the operator's namespace and the Home Assistant namespace on the Service port. Egress is left unrestricted (Home Assistant needs broad, unpredictable egress to IoT devices, cloud APIs, and MQTT brokers). NetworkPolicy operates on pod IPs — it does not restrict traffic arriving via the host network interface. Combining this with spec.hostNetwork: true gives only partial isolation. Deliberately without omitempty: this field represents explicit user intent, and the spec.alpha lifecycle plans to flip its default to true in a later phase — omitempty would let an explicit false be dropped and silently re-defaulted to true by the API server once that happens.	false	Optional: {}

RecorderConfig¶

RecorderConfig defines recorder (database) component configuration

Appears in: - HomeAssistantConfigurationSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled controls if the recorder is enabled	true	Optional: {}
`database` string	Database URL for the recorder (e.g., "postgresql://user:pass@host/db") If not specified, uses SQLite with default path. Mutually exclusive with DatabaseSecretRef; DatabaseSecretRef takes precedence.		Optional: {}
`databaseSecretRef` SecretKeySelector	DatabaseSecretRef references a Secret containing the database URL. The resolved value is written as plain text into configuration.yaml, avoiding the !secret tag which is stripped by the YAML round-trip. Takes precedence over Database if both are set. The Secret must be in the same namespace as the HomeAssistant CR.		Optional: {}
`purgeKeepDays` integer	PurgeKeepDays specifies how many days of history to keep	30	Minimum: 1 Optional: {}

SceneEntity¶

SceneEntity represents a single entity (device) in a scene with its desired state

Appears in: - HomeAssistantSceneSpec

Field	Description	Validation
`entity_id` string	EntityID is the Home Assistant entity identifier in format domain.object_id Examples: light.living_room, switch.fan, climate.bedroom	Pattern: `^[a-z_]+\.[a-z0-9_]+$` Required: {}
`state` string	State is the desired state for this entity Examples: "on", "off", numeric values	Required: {}
`attributes` RawExtension	Attributes contains additional entity-specific attributes Examples: brightness, color_temp, rgb_color for lights This is a flexible structure that accepts any valid Home Assistant entity attributes	Type: object Optional: {}

SchedulingSpec¶

SchedulingSpec declares Kubernetes-native pod scheduling constraints for the Home Assistant pod. Every field is optional and copied verbatim onto the generated StatefulSet's pod template; leaving all of them unset preserves today's freely-schedulable, default-priority behavior.

Appears in: - HomeAssistantSpec

Field	Description	Validation
`nodeSelector` object (keys:string, values:string)	NodeSelector restricts the pod to nodes matching all of these labels.	Optional: {}
`affinity` Affinity	Affinity declares node affinity/anti-affinity and pod affinity/anti-affinity rules, using Kubernetes' own Affinity semantics unchanged. Both node-level placement (e.g. "prefer nodes with local NVMe storage") and pod-level positioning relative to other workloads (e.g. "never share a node with this other deployment") are expressed through this single field, matching how corev1.Affinity itself groups NodeAffinity/PodAffinity/PodAntiAffinity together.	Optional: {}
`tolerations` Toleration array	Tolerations allows the pod to be scheduled onto nodes with matching taints that would otherwise repel it.	Optional: {}
`priorityClassName` string	PriorityClassName assigns a PriorityClass to the pod, influencing scheduling preemption and eviction order under resource contention. Must name an existing PriorityClass — validated at admission time.	Optional: {}

ScriptAction¶

ScriptAction defines an action to be executed by the script This is a flexible structure that accepts any valid Home Assistant action configuration

Appears in: - HomeAssistantScriptSpec

ScriptField¶

ScriptField defines an input parameter for the script This is a flexible structure that accepts any valid Home Assistant field configuration

Appears in: - HomeAssistantScriptSpec

ScriptMode¶

Underlying type: string

ScriptMode defines how the script should behave when called again while already running

Validation: - Enum: [single restart queued parallel]

Appears in: - HomeAssistantScriptSpec

Field	Description
`single`	ScriptModeSingle - Do not start a new run, issue a warning
`restart`	ScriptModeRestart - Stop previous runs and start a new one
`queued`	ScriptModeQueued - Queue runs in order, sequential execution guaranteed
`parallel`	ScriptModeParallel - Launch independent concurrent runs

SecretKeyReference¶

SecretKeyReference defines a reference to a specific key in a Kubernetes Secret.

Appears in: - HomeAssistantSecretsSpec

Field	Description	Default	Validation
`name` string	Name of the Secret		Required: {}
`keys` string array	Keys to extract from the Secret. If empty, all keys will be included.		Optional: {}

SecretKeySelector¶

SecretKeySelector selects a Secret and an optional key

Appears in: - MQTTConfig - RecorderConfig

Field	Description	Default	Validation
`name` string	Name of the Secret		Required: {}
`key` string	Key in the Secret (if not specified, defaults to "password" or "value")		Optional: {}

SecretReference¶

SecretReference references a Secret for sensitive data

Appears in: - HomeAssistantSpec

Field	Description	Default	Validation
`name` string	Name of the Secret

ServiceSpec¶

ServiceSpec defines how Home Assistant is exposed within the cluster.

Appears in: - HomeAssistantSpec

Field	Description	Default	Validation
`type` ServiceType	Type of Kubernetes Service (ClusterIP, NodePort, LoadBalancer)	ClusterIP	Enum: [ClusterIP NodePort LoadBalancer] Optional: {}
`port` integer	Port for the Home Assistant web UI	8123	Optional: {}
`nodePort` integer	NodePort for NodePort service type (optional, auto-assigned if not set)		Optional: {}

StorageSpec¶

StorageSpec defines storage configuration for Home Assistant.

Appears in: - HomeAssistantSpec

Field	Description	Default	Validation
`size` Quantity	Size of the persistent volume (e.g., "5Gi", "10Gi")	5Gi	Optional: {}
`storageClassName` string	StorageClassName for the PVC. If empty, uses cluster default.		Optional: {}
`accessMode` PersistentVolumeAccessMode	AccessMode for the PVC	ReadWriteOnce	Optional: {}
`retainPVC` boolean	RetainPVC controls whether the PVC survives deletion of the HomeAssistant CR. When true, no ownerReference is set on the PVC — it will not be garbage-collected when the CR is deleted (e.g. by FluxCD reconciliation), preventing accidental data loss. When false (default), the PVC is owned by the CR and deleted together with it.	false	Optional: {}
`initContainer` InitContainerSpec	InitContainer configures the init container that pre-creates required YAML files (automations.yaml, scenes.yaml, scripts.yaml) on the PVC before Home Assistant starts. This prevents HA from entering recovery mode when the !include directives are present but the files do not yet exist.		Optional: {}

TLSAlphaSpec¶

TLSAlphaSpec groups the (alpha) TLS integration modes backed by cert-manager.

Appears in: - AlphaSpec

Field	Description	Default	Validation
`native` NativeTLSAlphaSpec	Native enables Home Assistant to serve HTTPS natively (TLS terminated in HA itself on the same port), using a certificate issued by cert-manager.		Optional: {}